[Doxygen-develop] Comments... (was RE: [Doxygen-users] Multiple comments -combining )

[Prikryl,Petr <PRI...@sk...>]

(Sent to the developers list; the copy sent to doxygen users list -- please
reply in developers)

Hi doxygeners,

It seems that comments in doxygen are discussed more often
now.  Looking at doxygen architecture documentation 
(doxygen/html/arch.html), is there some clear separation 
between the comment parsing and the language construct
parsing?

I think that the separation of the two parsers should be done
before any important changes to comment parsing.  

Why I think so?  It would simplify the comment parsing
enhancements, and it would add flexibility of doxygen design.

The language parser would only recognize some blocks
of the language dependent comments as doxygen comments.
It will implement recognition of various flavours of doxygen
comments.  Its result will be the unified form of a doxygen
comment without language dependent syntactic things plus
some context information.  In other words, the language
parser will convert Qt style, JavaDoc style, block comments,
one-line comments, and whatever future style into one form
that will be passed to the comment parser.

If the language and comment parsers were separated, it 
would be much easier, for example, to process also in-body
comments (that some people asked for).

The comment parser then can be programming language 
indepedent.  This would allow implementing parsing for 
other programming languages.  But also, this would simplify
comment-enhancement development.  In the extreme case,
there could be a possibility to create external comment parsers
that would use different comment syntax.

Well crafted mechanism that will solve the requested
"multiple comment combining" could be used also for
in-body comments.

What is your opinion?

  Petr

-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

> -----Original Message-----
> From:	Stephen Goudge [SMTP:ste...@el...]
> Sent:	Thursday, November 15, 2001 9:13 AM
> To:	dox...@li...
> Subject:	RE: [Doxygen-users] Multiple comments -combining
> 
> The simple combining of comments is a feature that I'd certainly use.
> 
> As others (eg, Victor Wagner) do, we generate two lots of documentation
> from the sources for one library - one set from the public headers,
> detailing the API and examples for users, one with all the
> implementation detail for maintainers.
[...]