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

[Chris via Digitalmars-d]

On Thursday, 18 August 2016 at 14:31:47 UTC, Adam D. Ruppe wrote:
> On Thursday, 18 August 2016 at 13:19:13 UTC, Chris wrote:
>> Isn't there a way to auto-generate a minimal documentation 
>> with the help of the compiler? As in
>
> I think that would be useless for anything other than toy 
> functions. You can just view the source and learn more than 
> that.
>
> Good documentation tells you something that is hard to tell 
> from the source alone... it tells you there's a forest among 
> these trees.
>
> But even just plain tree thing, the doc can just list the 
> prototype and have a view source thing rather than try to parse 
> the code into English anyway.

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
*/