colour lib needs reviewers

Andrei Alexandrescu via Digitalmars-d digitalmars-d at puremagic.com
Thu Sep 15 11:55:45 PDT 2016


On 09/15/2016 02:34 PM, Jacob Carlborg wrote:
> 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].

That's fine because "Returns" is special-cased. Random words at the 
beginning of a line followed by ":" should not receive special treatment.

>> Can this be done by defining the expansion macros appropriately?
>
> What are "the expansion macros" ?

Those DDOC_XXX things that are used for formatting declarations.

>> 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

"Monkey see, monkey do." :o)

> * It's not a standard macro. If it's not here [2] nobody will find it or
> use it

Guess we can improve the (d)docs.

>> 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.

That'd be neat. As always, somebody's got to do it...


Andrei




More information about the Digitalmars-d mailing list