views:

27

answers:

1

I am designing a class library designed to solve a wide scope of problems. One thing about this library is that it will be usable by several different languages and environments natively. For example, there will be a C++ version written entirely in C++, a .NET version written in C# and a Java version written in Java, without any dependencies on each other... as opposed to writing the core library in C++ and simply providing .NET and Java bindings to it.

The library in each of its different forms sets out to solve a different but sometimes very similar set of problems. For example, there might be many classes whose members will be functionally identical in each language, and there will also be many classes that will be present in only one or two language-versions of the library, but not the others. Take a class or struct representing a program's version number. .NET already has such as class (System.Version) so I would not include it in my .NET version but the C++ and Java libraries would provide one.

The problem I am facing is that for classes which will exist in most or all versions of the library, the documentation will remain relatively the same (obviously). The brief text for both the C++ and Java version for a Version struct would be something like "Represents a software version number in the form major.minor.build.revision"... as would the detailed class description, and all the members' documentation, etc. As you know, .NET, Java and C++ all have their own documentation syntax. Is there any way I can attempt to consolidate documentation in a language-neutral way (WITHOUT writing the documentation separately from the source code - e.g. manual documentation as opposed to generating it using doxygen/sandcastle/javadoc) or am I stuck copying and pasting the same text into the source files of each version?

A: 

I was having the same issues and decided there were just two options for me:

  1. Using the same documentation generator in all languages. If you use doxygen (or ROBODoc, or whatever) for all of them, you would have just one doc syntax for all languages. This means that you have to break with language-specific conventions, though.
  2. Write your own doc parser. Which is hard work, especially for a language with quite complex syntactic rules (as C++.)

We are currently using doxygen for such projects.

soulmerge
I guess I have no choice but to duplicate. Code itself will be "duplicated" across different languages so I guess doing so for the documentation as well won't be too bad.
Jake Petroules