on DDoc macros: a small problem

[Charles Hixson]

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