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<[email protected]>:
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.
