On 2016-09-15 14:54, Andrei Alexandrescu wrote:

Yah, this is terrible (it happens with http: all the time). We need to
suppress the special meaning of ":" to only the cases when it's preceded
by only one word and followed by a newline, e,g, "\ncolor:\n".

It's useful for many of the sections to allow the section name on the same line as the content:

/// Returns: some useful value
int foo();

See the Ddoc documentation for more examples [1].

Can this be done by defining the expansion macros appropriately?

What are "the expansion macros" ?

Slashes are tolerable. The underscore I agree it's a quirk.

There are several (other) problems:

* How do I know I should use slashes? There's no documentation
* It's not a standard macro. If it's not here [2] nobody will find it or use it

That's a fair assessment, and an actionable one.

Perhaps the current implementation of Ddoc could be moved to a separate tool that would focus on being a macro system. That can still be used for the site and other documents. Ddoc in the compiler could be improved to be a better tool for documenting code. I think these are two separate use cases that might not be best accomplished with the same tool.

[1] http://dlang.org/spec/ddoc.html#standard_srction
[2] http://dlang.org/spec/ddoc.html#predefined_macros

--
/Jacob Carlborg

Reply via email to