On 2015-01-07 17:22, Andrei Alexandrescu wrote:
My summary of that discussion follows. There were quite a few radical
suggestions, some of which were interesting but that seemed to entail a
lot of work compared to the reaped benefits. (I have to say it was quite
fun to re-read the whole thread and see Walter calmly dismantling some
of the less valid arguments.)
The suggestions I think are actionable:
* Detect `xyz` and replace it with $(BACKQUOTED xyz), pull request in
progress at https://github.com/D-Programming-Language/dmd/pull/4228.
Maybe detect some __underscored__ or **bolded** words similarly.
* Better whitespace control
* Macros that expand without $() - possibly an extension of ESCAPES.
* Add a subset of markdown on top of ddoc (details unclear).
* Make [text](url) denote a link.
* Hashtags for headings
* Generate cross-references automatically.
* Clever automatic linking or embedding of overridden functions docs.
* Automatic links to source code.
* Simplified signatures (__FILE__ etc, template constraints)
* Replace some of the parens with indent nesting.
* Not in that thread, but it was somewhere proposed that we use
recursive macros for nice $(LIST item one, two, three).
What did I miss? Among the more radical proposals:
* Use markdown
* Use doxygen
Again, it seems to me these would yield little benefit for the effort
even assuming perfect execution.
Most of the ideas I had might require some redesign of the documentation
layout, these are:
* Summary of symbols
* Documentation for private symbols
* Simplified signatures
* Links to all base classes and interfaces of a class
* Links to all symbols from all base classes and interfaces
* Links to all known subclasses
BTW the thing that have bothered me the most when writing documentation
is there's no good way to even manually cross-reference symbols. We
really should have a special syntax for that as well.
--
/Jacob Carlborg
