Hello,
I'm working on generating documentation for the languages other than C++
from Doxygen comments in C++ code using SWIG (http://www.swig.org/). This
works by taking comments in C++ sources, optionally translating them to the
target language format (JavaDoc, reST/Sphinx, ...) and attaching them to
the classes/functions wrapping their C++ equivalents. Finally, either
Doxygen itself (if no translation has been done) or javadoc/sphinx (if the
comments were translated) can be used to produce the documentation for the
API in the other language.
Perhaps surprisingly, this process seems to work rather well and such
auto-translated documentation is genuinely useful. However, there still are
some problems, notably some C++ comments don't make any sense in the target
language context and have to be fixed manually.
The only way to do it I see is to add special Doxygen commands allowing to
indicate that some parts of the comments are for C++ documentation only.
And probably also, if only for symmetry, other commands that would on the
contrary only output something when generating documentation for the other
language and not C++, e.g.
/**
Some comment.
General description.
@forcpponly
C++-specific part.
@endforcpponly
@forpythononly
Python-specific part.
@endforpythononly
*/
Nothing is required to support this at Doxygen level as these commands
could just be defined as aliases using @if to determine whether they should
output something or not. But I'd like to ask if anybody here has already
done anything like this, even if manually, without involving SWIG, and
maybe has some hints to share?
And, also, just to avoid or at least reduce the risk of conflict with some
standard Doxygen command in the future, what should we call these commands?
I initially wanted to use just @pythononly/@endpythononly, for consistency
with the existing @docbookonly and such, but then decided that it would be
better to use something similar, but different, to emphasize that Python is
a programming language and not an output format. Would you have any advice
about this?
TIA for any thoughts!
VZ
|
