Improving ddoc

[Mathias LANG via Digitalmars-d]

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).