On 1/1/15 2:38 PM, Jacob Carlborg wrote:
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.
Sounds great, thanks.
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.
Full support would probably break a lot of extant documentation.
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
Nice.
* 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.
Nice!
* A list of summary with all symbols should be automatically generated
for a module
Shouldn't we leave that to postprocessing?
* Documentation for private symbols should be generated but hidden by
default in the output with a button to show them
Nice.
* A nice tree view with all packages and modules with filter for all
symbols
This seems like a matter of styling, not functionality.
* 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
Nice.
* Simplified signatures. Template constraints and default values which
are special symbols like __FILE__ or __LINE__ should be hidden by default
Nice.
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
Looks like a great list, thanks.
Andrei
