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

[Dimitri v. H. <di...@st...>]

On Fri, Nov 16, 2001 at 08:28:10AM +0100, Prikryl,Petr wrote:
> (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?

The separation is currently not as clean as it should be.
The language parser also contains pass one of the documentation
block parsing. Pass two is already moved to doc.l. 

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

I agree. I have this on my todo list for quite some time.
I am also trying to capture the documentation constructs in
some kind of formal grammar, but so far that isn't very 
successful :-(

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

Yes that is true, but combining comment blocks in a sensible 
and consistent way would still be equally difficult.

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

In the end that's what I'm aiming for, but for now I concentrate
on the XML generator & parser. The problem with plugin parsers
it that what they produce needs to be understood by the next
stage.

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

Good ideas on this are welcome. I still like the
idea proposed by someone to combine all comments in a body under
a section "Implementation details".

Regards,
  Dimitri