on DDoc macros: a small problem

[Charles Hixson]

On 02/20/2013 11:02 AM, Charles Hixson wrote:
> 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.

OK.  Tbe answer seems to be to include a module statement, and include 
documentations before the module statement. It's still a bit weird, as 
the Copyright: section isn't appearing, even though it's sandwiched in 
between a License: section and an Authors: section.  I don't really need 
the copyright in the documentation, though.  And it's in the source.