Doc generation with franca IDL

[kevron...@intel.com]

I've been using Franca IDL to describe my interfaces to make it easier for developers to generate bindings for their favorite language. However, using franca has come at a tradeoff. When using OMG idl, I was able to automatically create html and latex docs using doxygen in my build system (cmake). Since transitioning to franca, I've lost that ability. The lack of automatic doc generation is an unacceptable tradeoff and I'm debating transitioning back to OMG idl... which is undesirable and unfortunate.

To fix this with Franca, I can think of two possible remedies:

First would be to create a doxygen filter. There is already a feature for this in the issue tracker but it is low-priority. This would be the optimal solution IMO and should be made a higher priority.

Second would be the creation of a franca idl -> html doc command line tool. Having command line tools divorced from the controversial eclipse IDE would actually help Franca adoption overall IMO. It would make using Franca much more appealing to those of us who are not pleased with the eclipse system.

Regards,
Kevron

[Klaus Birken]

Hi Kevron,

thanks for pointing this out - indeed some way of including Franca interfaces in generated documentation would be useful and necessary (especially regarding the user base is increasing...). As a first step towards a better documentation generation support, I will increase the priority of the doxygen-related issue in the tracker, and have a look into how doxygen filters can be implemented.

Does anyone in this group has any experience in implementing a doxygen filter?

Best regards,

Klaus

[kevron...@intel.com]

Any thoughts on franca command line tools?

[Klaus Birken]

Hi,

we had some delays in developing a doxygen filter for fidl-files, because we focused on the release of Franca 0.9.1. But now we starting again with the activity, and I hope to have some preliminary results soon... 

Regarding a Franca -> html generator: The HTML generator which is shipped with Franca is only a demonstrator of how to develop Franca generators. We could make that standalone but this will not be very useful. We also could extend this HTML generator in order to support Franca fully, but then maybe everybody would like to have a different look and feel (can this be remedied by using css?). Kevron, do you have some more detailed requirements on how a html page generated from Franca should look like?

Best regards,

Klaus

[Klaus Birken]

Hi,

we now have built a solution for including Franca interfaces to doxygen documentation. In order to implement this, we implemented a translation from Franca to OMG-IDL and use this as a filter to process Franca files during the doxygen run. One problem which remains is that the transformation does not preserve the line numbers of the original file (which cannot be avoided because for some Franca elements we need a quite complicated mapping, for example Franca broadcasts). Maybe someone can contribute a solution for this...

Anyway, the filter can be run on the command line. I will be at the GENIVI AMM in Stuttgart on Thursday and present this new feature (among others). We didn't build a new Franca release which contains this feature yet, but I can provide a test version to interested users. We definitely need some beta testers...

Regards,

Klaus

[Sourabh Pandit]

Dear Birken,

I would be interested in getting the beta version of France.. 

Please let me know where to get it from.

Sourabh

[Sourabh Pandit]

Sorry it's. Franca ...

[Klaus Birken]

Hi,

I just sent you a link to the Doxygen filter and some instructions.

Happy testing,

Klaus

[anudee...@gmail.com]

Hello,

In which version of franca can i get this feature.

Please provide me link for the release which contains this feature

Regards,
Anudeep.

[Klaus Birken]

Hi Anudeep,

it is included since 0.9.2. See this presentation for some configuration details and issue 9 for some background information. 

If you want to try it, here is a compiled version including a shell script showing how to start this.

Looking forward to your feedback, regards,

Klaus

[anudee...@gmail.com]

Thanks for the response Klaus.

I would also like to know how i can use doxygen (If it is possible) for documenting my DSL(Component definition language).
The only way i know is writing a filter to convert it to code.

I am not interested in going with the above approach.

Any other way i can achieve this.

Regards,
Anudeep.

[Klaus Birken]

Hi,

which DSL do you refer to? It seems it is some DSL which you have built locally - is it available publicly? Another question: As you are active in this group, I guess from your component DSL you have references to Franca models?

I think doxygen is capable of documenting object-oriented source code, but might be not the right choice if it comes to components and their connections. You may convert a component and its ports and connections to class-like code, but this will add a lot of artificial complexity. This is probably not what someone wants when thinking about documentation. 

What you could do (if your DSL actually refers to Franca interfaces): Generate one doxygen documentation for the source code of each component including the required and provided interfaces. Generate (with a custom generator) a top-level documentation from your component model and link to the doxyfen documentations for each component. This concept will work nicely for the HTML-based docs, but maybe not so for pdf-documentation.

Hope this helps, regards,

Klaus