Ready to make page-per-item ddocs the default?

[Jacob Carlborg via Digitalmars-d]

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