colour lib needs reviewers

Jacob Carlborg via Digitalmars-d digitalmars-d at puremagic.com
Thu Sep 15 11:34:10 PDT 2016


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


More information about the Digitalmars-d mailing list