I think, it is a good idea to have both detailed and short description with link in second. But, may be, it isn't bad to start with a simple way - adding functionality to extend schema, and continue with improving it with detailed description in docs. Yes, I agree, that required parameter is better, but if we will be feeling not very conscientious, this required string may contain something useless too :) ------------------------------- Best regards, Alyona Kiseleva On Wed, Feb 11, 2015 at 9:39 PM, John Spray <john.spray@xxxxxxxxxx> wrote: > On Wed, Feb 11, 2015 at 6:02 PM, Gregory Farnum <greg@xxxxxxxxxxx> wrote: >> On Wed, Feb 11, 2015 at 9:33 AM, Alyona Kiseleva >> <akiselyova@xxxxxxxxxxxx> wrote: >>> Hi, >>> I would like to propose something. >>> >>> There are a lot of perf counters in different places in code, but the most >>> of them are undocumented. I found only one commented counter in OSD.cc code, >>> but not for all metrics. Name of counter is not very clear as it's >>> description, sometimes isn't at all. >>> >>> So, I have an idea, that it would be great, if perf schema would contain not >>> only the counter type, but some description too. It can be added in >>> PerfCountersBuilder methods - at first as optional parameter with empty >>> string by default, later, may be, as required parameter. This short >>> description could be saved in perf_counter_data_any_d struct together with >>> other counter properties and appear in perf schema as the second counter >>> property. > > There will be lots of counters that aren't usefully describable in a > single sentence. That doesn't excuse them from being documented, but > we should be careful to avoid generating useless tautological strings > like num_strays_delayed -> "Number of strays currently that are > currently delayed". For lots of things, an understandable definition > will require some level of introduction of terms and concepts -- in my > example, what's a stray? what does it mean for it to be delayed? > > While we shouldn't hold up the descriptions waiting for documentation > that explains all the needed concepts, we should think about how that > will fit together. Perhaps, rather than having a single string in the > code, we should look to create a separate metadata file that allows > richer RST docs for each setting, and verify that all settings are > described during the docs build (i.e. a gitbuilder fail will tell us > if someone added a setting without the associated documentation). > That way, the short perfcounter descriptions could include hyperlinks > to related concepts elsewhere in the docs. > > John -- To unsubscribe from this list: send the line "unsubscribe ceph-devel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
