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

[Dmitri Gribenko]

On Mon, Apr 28, 2014 at 5:55 PM, Alp Toker <alp at nuanti.com> wrote:
>
> On 28/04/2014 17:05, Dmitri Gribenko wrote:
>>
>> On Mon, Apr 28, 2014 at 4:57 PM, David Chisnall
>> <David.Chisnall at cl.cam.ac.uk> wrote:
>>>
>>> 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.
>>
>> Not only.  It also exposes a cooked comment in XML format with a
>> well-defined schema, that preserves the markup and semantic pieces of
>> the AST.  You can XSLT that XML into HTML.
>
> So it doesn't address any needs? Good we've cleared that up.

Alp, could you please stop using demagogic tricks and trying to pull
conclusions out of nowhere?  Indeed, I would like to remove comment
AST APIs in libclang, but not because they don't serve any purpose,
but because they introduce unnecessary ABI burden, while XML APIs in
libclang do not.  But we can not remove comment AST APIs from libclang
because of ABI stability guarantee.

> Nobody is asking for a second comment markup language in clang. This is a
> thread about removing the first one, a change for which there's already
> broad consensus.

I don't believe there is any other developer except you suggesting
anything like that.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/