www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - on DDoc macros: a small problem

reply Charles Hixson <charleshixsn earthlink.net> writes:
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.
Feb 19 2013
parent reply Johannes Pfau <nospam example.com> writes:
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
Feb 20 2013
next sibling parent Charles Hixson <charleshixsn earthlink.net> writes:
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.
Feb 20 2013
prev sibling parent reply Charles Hixson <charleshixsn earthlink.net> writes:
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.
Feb 20 2013
next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
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.
Feb 20 2013
parent Charles Hixson <charleshixsn earthlink.net> writes:
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.
Feb 20 2013
prev sibling parent Charles Hixson <charleshixsn earthlink.net> writes:
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.
Feb 20 2013