Generate also formatted docstring

[FanglinIfolor]

It's probably a good idea to also generate the formatted docstring. E.g.

my_cpp_interface = interface +c {
    # @brief Briefly explain what this function does
    # @param {i32} value: Briefly explain what value is
    method_returning_nothing(value: i32);

    # @brief Briefly explain what this function does
    # @param {string} key: Briefly explain what key is
    # @return {another_record}: Briefly explain what is returned
    method_returning_some_type(key: string): another_record;

Then it would convert to some common docstring formats for each language.

In our use case, initially we only used the generated Objective-C code for developing iOS apps, so we have written the docstring in Objective-C format. However, now we are also using the generated Java and C++/CLI code. As a result, the dll I built using C++/CLI code, no hints of how to use the class / function are shown.

Tried to search for it first, but it seems it was not discussed before. Correct me if there were already similar discussion. Thank you.

[jothepro]

I've stumbled across this problem as well. I like your idea to do docstring conversion!

To have at least some kind of documentation I am currently writing Doxygen-style comments in the IDL-file in order to then generate a documentation website with Doxygen for the generated Obj-C, Java, C++/CLI, C++ gluecode.

On top of what you propose I'd love the comments in the IDL to support Markdown for some basic text formatting (bold, italic, lists, tables, code-fragments...), which could then be converted to the equivalent HTML for Javadoc and C++/CLI XML documentation. But to achieve this a full blown markdown parser in the generator would be required. Sounds like a challenge...

[FanglinIfolor]

Supporting for Markdown would be super helpful, great idea, but agree that it would be definitely a challenge.

Off topic, would you mind to share more details of how you generate the documentation website with Doxygen for the generated Obj-C, Java, C++/CLI, C++ gluecode? I am particularly interested to know if you generate only once for all languages, or if you need to process separately for each language.

[jothepro]

To see how I am generating the Doxygen documentation you can have a look at this project template that I created for my own use. In the repository there is a Doxyfile for each language. The result is a separate documentation-website for each language: C++, Java, Obj-C, C++/CLI. With a dropdown selector in the top left of the website one can switch between languages.

But in practice despite having this fancy website most of the time I am just consulting the IDL file, that I am also publishing in the docs here... 😝

[FanglinIfolor]

Awesome! Thank you for sharing your project and experience. Would love to give it a try :).