Improving ddoc

[Andrei Alexandrescu via Digitalmars-d]

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