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
