[cfe-commits] [PATCH] Lexer for structured comments

[Douglas Gregor]

On Jun 26, 2012, at 1:41 PM, Sebastian Redl <sebastian.redl at getdesigned.at> wrote:

> As a general comment on the path this is taking, it seems like we're building a parser for a specific kind of structured comments right into Clang. (Maybe I'm misunderstanding, in which case you should ignore this mail.) Is this really what we want?

Yes, I think it is. We're looking at supporting the dominant documentation styles, to enable building more and better tools. Plus, Dmitri is building some extensibility in the parser, to make it easier to adapt to other styles. 

> Can't we completely outsource all lexing/parsing/AST building for structured comments to something completely separate, like a plugin?

Not if we want to provide good libclang integration, diagnostics, etc. 

> Doxygen and its relations are the most popular format for doc comments out there, but I personally am not at all fond of it. (Or Javadoc, or C# XMLDoc, etc.) I really don't like markup of any kind cluttering up the comments, often making them hard to read without prior processing. I would much prefer a Wiki-style comment format that looks good as unprocessed text too.

The dominant documentation styles could certainly be improved; no argument there. Even if we come up with something new and awesome, most of the headers you pull in will be in one of the dominant styles. 

> So at the very least, I would expect this default parser to not get in the way of completely different approaches.

The raw comment text will still be available, of course, and anything we do by default can be disabled.