[OT] of [OT] I am a developer and I hate documentation
Chris via Digitalmars-d
digitalmars-d at puremagic.com
Thu Aug 18 07:59:08 PDT 2016
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
*/
More information about the Digitalmars-d
mailing list