On Friday, 2 January 2015 at 09:40:45 UTC, Andrei Alexandrescu
wrote:
* Automatically generating cross-references
Nice.
https://github.com/rejectedsoftware/ddox/blob/master/README.md#ddox-documentation-engine
I'm still wondering why it's not shipped with DMD.
* A list of summary with all symbols should be automatically
generated
for a module
Shouldn't we leave that to postprocessing?
Agree. It would break one of the goal of Ddoc (It does not repeat
information that the compiler already knows from parsing the
code.)
Note that ddox also do that
http://vibed.org/api/vibe.core.concurrency/ . It's not perfect,
but you're sure it's always up to date, and is way more readable
than what Phobos is currently doing with BOOKTABLE.
* Documentation for private symbols should be generated but
hidden by
default in the output with a button to show them
Nice.
I don't see it being useful for Phobos, or any other library.
Have one doc with the public API available, optionally another
one for the framework/lib devs (but those often prefers the code).
* Simplified signatures. Template constraints and default
values which
are special symbols like __FILE__ or __LINE__ should be hidden
by default
Nice.
Strongly agree for the constraints. For __FILE__ & __LINE__, what
would it affects ? I can think of exception-related stuff,
anything else ?
Also, I was very puzzled with $(D) when I was looking for the
right way to use it. I think the answer is relevent to this
dicussion:
https://github.com/rejectedsoftware/vibe.d/pull/875
Most of the issues, IMO, are stylistic. We should firstly work on
improving the output, rather than introduce new syntax.
Also, documentation is much more subjective than code (just like
success and adult content :o) ). We could introduce control flags
to ensure some minima are met, examples that come to mind are:
--ddoc-werror (build failure on doc warning),
--ddoc-require=params,returns (require Params and Returns
sections to be defined, those can be empty for trivial functions),
--ddoc-document=public (require every public symbols to be
documented).
