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.

Am Tue, 19 Feb 2013 16:43:09 -0800
schrieb Charles Hixson <charleshixsn@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

On 02/20/2013 12:51 AM, Johannes Pfau wrote:
> Am Tue, 19 Feb 2013 16:43:09 -0800
> schrieb Charles Hixson<charleshixsn@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

Thank you.  I had read http://dlang.org/ddoc.html, but what I got out of it was that a macro was concluded when the parentheses balanced. Looking over it, though, I see that in the Note macro they balanced twice, so I wasn't understanding in a consistent way.

On 02/20/2013 12:51 AM, Johannes Pfau wrote:
> Am Tue, 19 Feb 2013 16:43:09 -0800
> schrieb Charles Hixson<charleshixsn@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.

On Wed, Feb 20, 2013 at 11:02:51AM -0800, 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@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'm not sure if I'm completely off-base here, but have you tried inserting a space between the macro name and its parameters? Like:

	Em = $(B $(BLUE $0))

Does that make a difference?

If not, I'd say you should file a bug in the issue tracker (d.puremagic.com/issues) so that people won't forget it needs to be fixed.


T

-- 
Never wrestle a pig. You both get covered in mud, and the pig likes it.

On 02/20/2013 11:10 AM, H. S. Teoh wrote:
> On Wed, Feb 20, 2013 at 11:02:51AM -0800, 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@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'm not sure if I'm completely off-base here, but have you tried
> inserting a space between the macro name and its parameters? Like:
>
> 	Em = $(B $(BLUE $0))
>
> Does that make a difference?
>
> If not, I'd say you should file a bug in the issue tracker
> (d.puremagic.com/issues) so that people won't forget it needs to be
> fixed.
>
>
> T
>
I think you're misunderstanding the problem.  If I place the macro section after another documentation comment, then it *works*, sort of, it just includes the following documentation comment as an extension of the Em macro...unless I follow it with another macro definition.

I can't get a file description to print, only descriptions of individual routines.  I can't have a file author, only authors of individual routines, variables, etc.  I can't have a copyright on the file, only copyrights on individual routines.  ETC.

Most of this is just annoying.  I don't really need a copyright notice in the documentation, etc.  But not having a version or a description at the file level is a major pain.  And it leads to an extremely contorted syntax where the macros need to be defined after the first routine has been documented.

Another annoyance is the way the comments are so verbose.  I need to use two lines instead of one to document a single parameter to a routine. This makes things hard to follow in the code, because the code is continually being scrolled off the screen to make room for documentation comments.  (I really need a much larger screen, but I don't have space in my work area.)  Doxygen comments are much nicer in this way.

But I don't really think these are bugs.  I think they're design decisions.  Bad ones in my opinion, but I didn't design it.  And I haven't found a decent alternative if I need to handle "extern(C)" code in my documentation.

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