Question

Can I somehow generate documentation for 2 different languages with same code? Problem is that I have a C API that is also exposed trough a proprietary language that resembles VB.

So the exposed function in C is something like:

int Function (*PointerToObject)

While in VB it would be something like:

int Function (ByVal long PointerToObject)

I already opened another thread before about this same problem, but by that time I did not know anything about Doxygen. The last couple of days I have been reading the documentation and apparently it can create documentation for VB, but I have to have actual VB code for it to work and I don’t. The only thing I have is the original C and the swig output also in C.

What I have in mind is some tool (doxygen, sphinx,…) that would enable me to create some kind of multi-language documentation from a single source (not valid doxygen, but explains the idea):

/*! \fn int Function(*PointerToObject) 
 *  \brief A simple function.
 *  \Cparam[in] PointerToObject A pointer to the object being used.
 *  \VBparam[in]    ByVal long PointerToObject      A pointer to the object being used.
 *  \return An integer.
 */

It would be great if I could somehow integrate it to swig since it is swig that identifies the correct VB type, but I guess I maybe be asking too much.

It is a bit complicated, if I am not clear enough please leave a comment I will try to explain it further.

Answer 1

I’m not positive how useful this will be as I haven’t done precisely what you’re looking for (and it is a bit of a kludge), but under similar circumstances I came to the conclusion that our best bet was to generate a fluff object just for doxygen to document.

In our case we have an LDMud which has a few hundred driver-published external functions which don’t exist in the LPC language the rest of the MUD is written in. We could parse it in its native C code as a separate documentation run and include the docs with our primary documentation. In our case we have fairly thorough plain-text documentation including what we should consider the definition of these functions to be, so we use this documentation instead to generate an object with dummy function definitions and parse the plaintext documentation into function-head comments in doxygen style. This obviously doesn’t provide us the advantages of including code or in-code comments with the documentation, but it does allow us to generate the documentation in multiple forms, push it around in guides, make references to these functions from other documentation, etc.

I’m not directly familiar with C so I’m not sure if there’s any introspective support for performing a programmatic inventory of the functions you need and generating dummy declarations from that information or not. If you don’t and have a small number of functions I suspect it would be the best investment of your time to simply write the dummy declarations by hand. If you have a really large number of these functions it may be worth your time to use doxygen to parse the original code into XML documentation, and generate the dummy object(s) from the XML. Doxygen’s XML can be a pain to deal with, but if all you really need is the declaration and arguments it is (relatively) simple.

As a final aside, if your documentation can really be thought of as internal and external, you might also want to use two or more configuration files to generate different sets of documentation saved to different locations and publish them separately to your internal/external audiences. It will make the task of providing the right amount of detail to each less frustrating. Along those lines you may also find the INTERNAL_DOCS option and the @internal / @endinternal commands useful.