doxygen-users

[Doxygen-users] Fwd: Identifying Objective-C code from the XML

[Michael J. <m.p...@gm...>]

Hi,

I am the maintainer of an open source project called Breathe which relies
on the excellent xml output from Doxygen to include Doxygen processed code
& comment information in Sphinx documentation.

Breathe has generally focussed on C & C++ output but recently we've had
requests to support Objective-C code as well which has very different
formatting. As Breathe doesn't know any better it attempts to stick the
information in the XML together as if it is C style output and so produces
a bit of a mess for Objective-C style declarations.

I am curious how doxygen tracks that a particular declaration should be
output as Objective-C and how that might be reflected in the XML output in
such as way that Breathe might take advantage of it.

Unfortunately, I know very little of Objective-C so I don't really know
what I am looking for. That said, from an inspection of the XML output for
an example Objective-C interface the only clues I can see are that the
'ids' begin with 'interface' and that there are strangely placed square
brackets and colons in the definition & param values :)

Is the 'interface' prefix sufficient information in this case? Is there
another way of determining that Objective-C might be involved?

Any help would be greatly appreciated,
Michael


ps. I sent this before but without subscribing to the list so I suspect it
was held in a queue. I attempted to cancel it upon sending this but my
token had expired.

Re: [Doxygen-users] Identifying Objective-C code from the XML

[Dimitri v. H. <do...@gm...>]

Hi Michael,

> On 26 Oct 2014, at 12:15 , Michael Jones <m.p...@gm...> wrote:
> 
> I am the maintainer of an open source project called Breathe which relies on the excellent xml output from Doxygen to include Doxygen processed code & comment information in Sphinx documentation.

A very interesting project!

> Breathe has generally focussed on C & C++ output but recently we've had requests to support Objective-C code as well which has very different formatting. As Breathe doesn't know any better it attempts to stick the information in the XML together as if it is C style output and so produces a bit of a mess for Objective-C style declarations.
> 
> I am curious how doxygen tracks that a particular declaration should be output as Objective-C and how that might be reflected in the XML output in such as way that Breathe might take advantage of it.
> 
> Unfortunately, I know very little of Objective-C so I don't really know what I am looking for. That said, from an inspection of the XML output for an example Objective-C interface the only clues I can see are that the 'ids' begin with 'interface' and that there are strangely placed square brackets and colons in the definition & param values :)
> 
> Is the 'interface' prefix sufficient information in this case? Is there another way of determining that Objective-C might be involved?

Doxygen internally keeps track of which language a symbol is written in (see Definition::getLanguage()).
This information is partly based on the file extension (and EXTENSION_MAPPING setting) and is for Objective-C also based on specific keywords found in the header file.

So far this information is not written to the XML output, but it would not be hard to add this if that would help you.

Regards,
  Dimitri

Re: [Doxygen-users] Identifying Objective-C code from the XML

[Michael J. <m.p...@gm...>]

Hi,

Thank you for the quick response. I'm glad you think the project is
interesting and I am very grateful for the links you provide to Breathe
from your documentation.

It is good to know Doxygen stores the language for the definitions. For
Breathe, it certainly would be useful to have the source language in the
XML output as it seems the code needs to make similar rendering decisions
as your HTML output code does. I'm not sure how best to represent it or at
what level to have it specified. I imagine you have a good feel for that.
Being inexperienced at Objective-C I get confused, but I guess the ability
to mix Objective-C and plain C style declarations means it would have to go
on each definition rather than any higher up.

If you think it is acceptable for the XML output then great, if you can see
a better approach then I'd be happy to learn. Thanks again.

Kind regards,
Michael


On Sun, Oct 26, 2014 at 11:54 AM, Dimitri van Heesch <do...@gm...>
wrote:

> Hi Michael,
>
> > On 26 Oct 2014, at 12:15 , Michael Jones <m.p...@gm...> wrote:
> >
> > I am the maintainer of an open source project called Breathe which
> relies on the excellent xml output from Doxygen to include Doxygen
> processed code & comment information in Sphinx documentation.
>
> A very interesting project!
>
> > Breathe has generally focussed on C & C++ output but recently we've had
> requests to support Objective-C code as well which has very different
> formatting. As Breathe doesn't know any better it attempts to stick the
> information in the XML together as if it is C style output and so produces
> a bit of a mess for Objective-C style declarations.
> >
> > I am curious how doxygen tracks that a particular declaration should be
> output as Objective-C and how that might be reflected in the XML output in
> such as way that Breathe might take advantage of it.
> >
> > Unfortunately, I know very little of Objective-C so I don't really know
> what I am looking for. That said, from an inspection of the XML output for
> an example Objective-C interface the only clues I can see are that the
> 'ids' begin with 'interface' and that there are strangely placed square
> brackets and colons in the definition & param values :)
> >
> > Is the 'interface' prefix sufficient information in this case? Is there
> another way of determining that Objective-C might be involved?
>
> Doxygen internally keeps track of which language a symbol is written in
> (see Definition::getLanguage()).
> This information is partly based on the file extension (and
> EXTENSION_MAPPING setting) and is for Objective-C also based on specific
> keywords found in the header file.
>
> So far this information is not written to the XML output, but it would not
> be hard to add this if that would help you.
>
> Regards,
>   Dimitri
>
>

Re: [Doxygen-users] Identifying Objective-C code from the XML

[Michael J. <m.p...@gm...>]

Hi,

I'm sorry to have gone quiet. Do you feel that you have time to look at
this? Or do you think that it is a reasonable feature for someone new to
the code base to try? I could attempt a pull-request and you could provide
feedback?

Kind regards,
Michael

On Sun, Oct 26, 2014 at 4:02 PM, Michael Jones <m.p...@gm...>
wrote:

> Hi,
>
> Thank you for the quick response. I'm glad you think the project is
> interesting and I am very grateful for the links you provide to Breathe
> from your documentation.
>
> It is good to know Doxygen stores the language for the definitions. For
> Breathe, it certainly would be useful to have the source language in the
> XML output as it seems the code needs to make similar rendering decisions
> as your HTML output code does. I'm not sure how best to represent it or at
> what level to have it specified. I imagine you have a good feel for that.
> Being inexperienced at Objective-C I get confused, but I guess the ability
> to mix Objective-C and plain C style declarations means it would have to go
> on each definition rather than any higher up.
>
> If you think it is acceptable for the XML output then great, if you can
> see a better approach then I'd be happy to learn. Thanks again.
>
> Kind regards,
> Michael
>
>
> On Sun, Oct 26, 2014 at 11:54 AM, Dimitri van Heesch <do...@gm...>
> wrote:
>
>> Hi Michael,
>>
>> > On 26 Oct 2014, at 12:15 , Michael Jones <m.p...@gm...>
>> wrote:
>> >
>> > I am the maintainer of an open source project called Breathe which
>> relies on the excellent xml output from Doxygen to include Doxygen
>> processed code & comment information in Sphinx documentation.
>>
>> A very interesting project!
>>
>> > Breathe has generally focussed on C & C++ output but recently we've had
>> requests to support Objective-C code as well which has very different
>> formatting. As Breathe doesn't know any better it attempts to stick the
>> information in the XML together as if it is C style output and so produces
>> a bit of a mess for Objective-C style declarations.
>> >
>> > I am curious how doxygen tracks that a particular declaration should be
>> output as Objective-C and how that might be reflected in the XML output in
>> such as way that Breathe might take advantage of it.
>> >
>> > Unfortunately, I know very little of Objective-C so I don't really know
>> what I am looking for. That said, from an inspection of the XML output for
>> an example Objective-C interface the only clues I can see are that the
>> 'ids' begin with 'interface' and that there are strangely placed square
>> brackets and colons in the definition & param values :)
>> >
>> > Is the 'interface' prefix sufficient information in this case? Is there
>> another way of determining that Objective-C might be involved?
>>
>> Doxygen internally keeps track of which language a symbol is written in
>> (see Definition::getLanguage()).
>> This information is partly based on the file extension (and
>> EXTENSION_MAPPING setting) and is for Objective-C also based on specific
>> keywords found in the header file.
>>
>> So far this information is not written to the XML output, but it would
>> not be hard to add this if that would help you.
>>
>> Regards,
>>   Dimitri
>>
>>
>

Re: [Doxygen-users] Identifying Objective-C code from the XML

[Dimitri v. H. <do...@gm...>]

Hi Michael,

I've already implemented the language attribute, see this commit
https://github.com/doxygen/doxygen/commit/e986e0039de21791bd1fbb1f59b13f58c4a46324

Feedback about the usefulness is very much welcome of course.

Regards,
  Dimitri

> On 30 Nov 2014, at 12:35 , Michael Jones <m.p...@gm...> wrote:
> 
> Hi,
> 
> I'm sorry to have gone quiet. Do you feel that you have time to look at this? Or do you think that it is a reasonable feature for someone new to the code base to try? I could attempt a pull-request and you could provide feedback?
> 
> Kind regards,
> Michael
> 
> On Sun, Oct 26, 2014 at 4:02 PM, Michael Jones <m.p...@gm...> wrote:
> Hi,
> 
> Thank you for the quick response. I'm glad you think the project is interesting and I am very grateful for the links you provide to Breathe from your documentation.
> 
> It is good to know Doxygen stores the language for the definitions. For Breathe, it certainly would be useful to have the source language in the XML output as it seems the code needs to make similar rendering decisions as your HTML output code does. I'm not sure how best to represent it or at what level to have it specified. I imagine you have a good feel for that. Being inexperienced at Objective-C I get confused, but I guess the ability to mix Objective-C and plain C style declarations means it would have to go on each definition rather than any higher up.
> 
> If you think it is acceptable for the XML output then great, if you can see a better approach then I'd be happy to learn. Thanks again.
> 
> Kind regards,
> Michael
> 
> 
> On Sun, Oct 26, 2014 at 11:54 AM, Dimitri van Heesch <do...@gm...> wrote:
> Hi Michael,
> 
> > On 26 Oct 2014, at 12:15 , Michael Jones <m.p...@gm...> wrote:
> >
> > I am the maintainer of an open source project called Breathe which relies on the excellent xml output from Doxygen to include Doxygen processed code & comment information in Sphinx documentation.
> 
> A very interesting project!
> 
> > Breathe has generally focussed on C & C++ output but recently we've had requests to support Objective-C code as well which has very different formatting. As Breathe doesn't know any better it attempts to stick the information in the XML together as if it is C style output and so produces a bit of a mess for Objective-C style declarations.
> >
> > I am curious how doxygen tracks that a particular declaration should be output as Objective-C and how that might be reflected in the XML output in such as way that Breathe might take advantage of it.
> >
> > Unfortunately, I know very little of Objective-C so I don't really know what I am looking for. That said, from an inspection of the XML output for an example Objective-C interface the only clues I can see are that the 'ids' begin with 'interface' and that there are strangely placed square brackets and colons in the definition & param values :)
> >
> > Is the 'interface' prefix sufficient information in this case? Is there another way of determining that Objective-C might be involved?
> 
> Doxygen internally keeps track of which language a symbol is written in (see Definition::getLanguage()).
> This information is partly based on the file extension (and EXTENSION_MAPPING setting) and is for Objective-C also based on specific keywords found in the header file.
> 
> So far this information is not written to the XML output, but it would not be hard to add this if that would help you.
> 
> Regards,
>   Dimitri
> 
> 
>