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