on DDoc macros: a small problem

[Charles Hixson]

On 02/20/2013 12:51 AM, Johannes Pfau wrote:
> Am Tue, 19 Feb 2013 16:43:09 -0800
> schrieb Charles Hixson<charleshixsn at earthlink.net>:
>
>> I have, towards the start of my file:
>>
>>    /** Macros:
>>    * Note = $(BR)$(BIG$(B$(GREEN  Note:)))
>>    * Todo =<br><font color=red><b>ToDo:</b>  $0</font><br>
>>    * Em = $(B$(BLUE $0))
>>    * DoNotUse = $(B Do Not Use $0)
>>    */
>>
>> Why do I need that DoNotUse macro to terminate the Em macro?  If I
>> don't include it, the Em macro picks up the first line of the next
>> documentation comment, and includes it as a part of itself.  I'm
>> clearly doing something wrong, but I have no idea what.
>
> I guess if you include the DoNotUse macro, the next line will just be
> part of it. That's because we somehow have to support multi-line
> macros. A macros is only finished if a new macro is started or a new
> Section starts. So you'll have to either write your text above the macro
> section or you have to start a new section:
>
> /**
>   * Summary text goes here
>   *
>   *Macros:
>   * Note = $(BR)$(BIG$(B$(GREEN  Note:)))
>   * Todo =<br><font color=red><b>ToDo:</b>  $0</font><br>
>   * Em = $(B$(BLUE $0))
>   *Note:
>   * More text here
>   */
>
> More information: http://dlang.org/ddoc.html

I'm guessing, and it's only a guess, after reading that link over again, 
that there's no concept of documenting a file, or setting a section that 
applies, at least by default, to everything in the file.  So, for 
example, one is expected to supply a separate author, license, 
copyright, date, etc. for every variable, struct, method, class, etc. 
And that it's pure happenstance that if I define a macro earlier in the 
file, that I can continue to use it later.

In that case the results I've been getting make sense, however 
disgusting they are.