Improving ddoc

[Jacob Carlborg via Digitalmars-d]

On 2014-12-31 20:50, Andrei Alexandrescu wrote:

> In wake of the recent discussions on improving ddoc syntax we're looking
> at doing something about it. Please discuss any ideas you might have
> here. Thanks!

I think there are two big issues with Ddoc: its syntax and its lack of 
functionality. I think the major reason for these issues is that Ddoc is 
a general text macro tool. Personally I would just throw out Ddoc and 
start completely fresh, I know that is too extreme so I'm not suggesting 
that.

I think the solution is to use Ddoc as it is today, with full support 
for Github flavored Markdown added and a couple of other enhancements. 
The reason is listed below:

I'm not going to argue so much about the syntax since many others have 
already done so.

The functionality that I feel is missing:

* Automatically generating cross-references

* Inhering documentation. Methods that override some other method should 
automatically inherit the documentation of the overridden method, unless 
there's already documentation present for that method or explicitly 
disable the inheritance with a command.

* A list of summary with all symbols should be automatically generated 
for a module

* Documentation for private symbols should be generated but hidden by 
default in the output with a button to show them

* A nice tree view with all packages and modules with filter for all symbols

* Automatically create links to the source code for each symbol. This 
could either be to syntax highlighted source code Ddoc generates or to 
Github. There could be a flag (or some other way) to specify which 
Github project to link to

* Simplified signatures. Template constraints and default values which 
are special symbols like __FILE__ or __LINE__ should be hidden by default

The following should automatically be generated for a given class:

* 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

That are just a couple of suggestions. Just take a look at some existing 
documentation for other language and see what's missing [1], [2].

[1] 
http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html

[2] http://www.scala-lang.org/api/current/#scala.collection.Iterable

-- 
/Jacob Carlborg