[cfe-dev] Adding more HTML-related facilities in Doxygen comment parsing

[David Chisnall]

On 28 Apr 2014, at 16:40, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> HTML is a part of Doxygen.  If we are not doing it, then we are
> implementing our own documentation language that no other person in
> the world cares about.  This is as if someone said, "I don't use
> partial specialization of templates in C++, so Clang should not be
> implementing it."

I think you are missing the point.  The Clang libraries parse C++ into an AST, which is a clang-specific data structure.  That's fine, because there aren't many other libraries that expose C++ AST data structures that users of clang want to interoperate with.  Clang then generates LLVM IR and object code from C++, using well-defined (or, in some cases, poorly defined, but at least vaguely standardised) ABIs.

This is in direct contrast to a consumer of documentation, which may want to integrate with one of many different libraries that already provide complex data structures and APIs for handling rich text.  

Currently, libclang exposes the 'comment AST', which is an unwieldy thing that doesn't seem to address any needs.  As a consumer of the documentation, I either want:

- To parse the doc comments myself.

- To have them transformed into something that I can easily consume with an existing parser (e.g. HTML).

You also seem to be under the impression that doxygen is the only markup language that is found in [Objective-]C[++] source files.  For Objective-C, Apple's HeaderDoc and GSDoc are more popular, but there are half a dozen other less-popular one.  

I fully support interfaces in libclang that allow plugins for different comment markup languages, but deciding to hard-code one (and one that is poorly defined and apparently allows all of HTML 5) seems like a terrible idea.  

David