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
