[OT] of [OT] I am a developer and I hate documentation

[Marco Leise via Digitalmars-d]

Am Thu, 18 Aug 2016 14:59:08 +0000
schrieb Chris <wendlec at 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