scx_stats: Implement macro #stat_doc to autogen doc from stat desc #703
Conversation
|
Adding screenshot of generated rust doc: 
|
|
Looks like a slight linter error on the workflow for |
The doc of scx_layered `Opt` is out of sync. Implement attribute macro #stat_doc to generate doc from the `desc` property. Apply #stat_doc to `LayerStats` and `SysStats in scx_layered. Signed-off-by : Ming Yang <[email protected]>
| new_attrs.push(attr); | ||
| } | ||
|
|
||
| // If a description string was found, add a #[doc = "..."] attribute |
There was a problem hiding this comment.
Can we just rename desc field to doc?
There was a problem hiding this comment.
changing #[stat(desc = "...")] into #[stat(doc = "...")] won't make it into the generated documentation because doc attribute is actually #[doc = "..."].
Also, desc in stat macro here is put into the StatsMeta, for example, here is the expanded rust code:
with the change in this PR, the original struct is extended with document like the following, where /// ... lines are added by the stat_doc macro.
There was a problem hiding this comment.
Hmmm... I wonder whether it should be synced the other way then - ie. let scx_stats macro to take the /// comment and turn that into description field. What do you think?
There was a problem hiding this comment.
I think it should be the current way. Documents can be out of rules, while a desc property feels constrained to be one short sentence. In the current way, it's also composable as one can add more doc in comment. So other than sync, it's more an extension to the doc from the desc property. Screenshots for a demo are attached:
There was a problem hiding this comment.
Understood. Thanks for the explanation and the PR!
| @@ -55,9 +57,9 @@ pub struct LayerStats { | |||
| pub load: f64, | |||
| #[stat(desc = "fraction of total load")] | |||
| pub load_frac: f64, | |||
| #[stat(desc = "# tasks")] | |||
| #[stat(desc = "count of tasks")] | |||
There was a problem hiding this comment.
Are these changes beacause doc doesn't allow hash sign?
There was a problem hiding this comment.
it's because the hash sign in the front indicates heading in markdown.
The doc of scx_layered
Optis out of sync.Implement attribute macro #stat_doc to generate doc from the
descproperty, and apply #stat_doc toLayerStatsandSysStatsin scx_layered.Also fix typo and replace
#with "count of" to avoid messing with markdown syntax in the generated rust doc.Signed-off-by : Ming Yang [email protected]