Objective-C: is it supported?

[biasmv]

Hi,

We would like to generate documentation for Objective-C using breathe. Is this use-case supported out of the box? We have tried to use it as is, but were running into problems.

• the method signatures are garbled. For example, foo:(int)a withA:(int)A andB:(int)B; is rendered as foo:withA:andB:(int,int,int). Is this something we have to take care of in our template?
• how does one link to an objective-C class? Or put another way, what is the equivalent of :cpp:class: for objective-C classes?

Thank you very much

[michaeljones]

Hi Biasmv,

Thanks for trying breathe. I'm afraid the Objective-C support is pretty weak at the moment. It hasn't really been raised much in the passed so it hasn't had the attention it deserves. It was recently raised on the discussion group here:

https://groups.google.com/forum/?hl=en#!topic/sphinx-breathe/r55170_Bdz8

I have replied but it seems that my reply must have gone straight to the sender. I am keen to have objective-C support though. The sender JoeWard has shared his current implementation of Objective-C support for an old version of Breathe here:

https://github.com/jo3w4rd/breathe 

The "working" branch is what I am currently using, but "objectiveccategories" should have just the changes related to Objective-C.

As for your questions:

• Breathe doesn't really offer templating for customising the output. Improvements to the output would have to be handled in the main code and for this we'd need to detect that we're working with an objective-C file.
• The :cpp: domain is provided by Sphinx itself, we just attempt to provide compatible targets for it. It doesn't look like Sphinx provides an Objective-C domain and there doesn't seem to be one in the sphinx-contrib repository either. We could look into trying to provide one but it would be best as a separate project and I have no experience with creating domains at this point.

I hope that summarises the situation. I am sorry that it isn't better news at the moment. If you feel like you have time to contribute something, I would look into the Objective-C domain if I were you. It is possible there is one out there already but not registered with the Sphinx-contrib repository.

Cheers,
Michael

[biasmv]

Hi Michael,

thanks your answers. That's what I've been looking for. I've contacted JoeWard regarding his version containing Objective-C support. I'm very interested in getting this committed to mainline and will check together with him on how exactly to do that.

Having proper support for displaying method signatures in Objective-C is my main goal, having a proper domain is secondary as there seem to be ways around it. JoeWard, for example uses text substitutions to generate links which seems work just fine, even if it's a hack.

Best,
Marco

[michaeljones]

I've just started looking at this a little more closely. Can you tell me how often you use the .m file extension for Objective-C code? Is that always the case or do you use Objective-C in .h files too?

From a simple test with a .m file and an interface declaration, it seems that doxygen carries the 'interface' key word into the xml output, though only in the id names. That might be enough for us to render the output differently.

Maybe @jo3w4rd would be interested in this too.

[biasmv]

The interface definitions I would like to document are all in .h files.The id names of Obj-C interfaces in headers are also prefixed with interface_. I am imagining that doxygen also creates ids with interface_ prefixes for Java interfaces. The combination of an interface_ prefix together with one of the Obj-C supported file extensions (.m, .h, .mm) should be enough tough.

[jo3w4rd]

My doc comments are also in the .h files. Objective-C also has categories and protocols, which don't use "interface". They do have their own "kind" attribute value, though.

[michaeljones]

Cheers guys. I've emailed the doxygen-users list to ask if there is or could be any additional information in the xml files that would help with this situation. The ideal scenario being that doxygen provides a clear indication of what is expected. Though I agree that the file extension + id prefix might be sufficient.

Could you guys do me a favour and put together a small example file that covers the range of Objective-C code that you would like to see handled properly? It would be great to have a reference and to work through.

[michaeljones]

Hi guys,

The doxygen author has kindly added language attributes into the XML output so we get informed of what language doxygen thinks is being used for every class, function, etc.

doxygen/doxygen@e986e00

This should gives us a really good base to work from. I've not looked at it closely but I'm going to try to do so and get Breathe working with the values to get some objective-c output happening.

Hope you guys are still interested and that working with the latest and greatest doxygen is an option for you.
Michael

[biasmv]

Hi Michael,

thanks for continuing to look into this. Priorities have shifted in the meantime and I didn't have time to give it the attention it deserves. I'm definitely still interested. Using then newest doxygen is not a problem for me.

Best,
Marco

[vitaut]

This will require adding Objective C support in Sphinx (an Objective C domain), so I suggest opening an issue there and closing this one until there is at least minimal support for this language in Sphinx. Currently there is nowhere to map Doxygen constructs.

[vermeeren]

As said above this requires an Objective C domain in Sphinx itself, either native or as extension.

For some additional details refer to my recent comment on #249.

Closing for now as there is no support or extension as far as I can find quickly.