Am Thu, 18 Aug 2016 14:59:08 +0000 schrieb Chris <wend...@tcd.ie>: > On Thursday, 18 August 2016 at 14:31:47 UTC, Adam D. Ruppe wrote: > It would be a good starting point for documentation stubs, not a > substitute for a proper, full-fledged documentation. The most > annoying thing about writing docs is the amount of boilerplate, > not the doc itself, cf: > > /** > Find $(D value) _among $(D values), returning the 1-based index > of the first matching value in $(D values), or $(D 0) if $(D > value) > is not _among $(D values). The predicate $(D pred) is used to > compare values, and uses equality by default. > Params: > pred = The predicate used to compare the values. > value = The value to search for. > values = The values to compare the value to. > Returns: > 0 if value was not found among the values, otherwise the > index of the > found value plus one is returned. > > [...] > */ > > If `Params` and `Returns` were generated automagically, at least > as stubs, then it would be easier to write the "true" > description, i.e. if you had something like: > > /** > <Description here> > Params: > pred = > value = > values = > Returns: > (unit) 0 || index + 2 > */
My take on it is to document the Params where they are declared: int mul2(int x /** the value to be multiplied by 2 */) { return 2*x; } People have been doing that in the past with or without documentation generators for the benefit that you don't need to repeat yourself and don't need to update the docs after an argument name refactoring. By the way, AFAIK someone implemented `code` as an alternative to $(D code) quite a while ago. So you can use that instead. I'd like ordered/unordered lists to also follow markup style one day. I find it more natural and readable than $(OL $(LI first item) $(LI another important thing) ) -- Marco