[capi-sig] Documenting a C/Py API

[Hrvoje Niksic]

Campbell Barton <cbarton at metavr.com> writes:

> Ideally Id like to only maintain 1 set of docs... so possibilities
> are
[...]

If you maintain only one set of docs, then your options are indeed
limited.  I tend to agree with Carsten that docstrings and full
documentation are in fact different; docstrings tend to be briefer,
don't provide examples, and in fact don't have real formatting.
Attempts to add HTML-like formatting to docstrings lead to them not
being readable from Python, which defeats the purpose.  The Python
source is a precedent for maintaining two sets of documentation and
for the distinction between them.

We currently document the C-implemented classes with Doxygen by
writing dummy classes with markup that Doxygen understands.  The line
numbers are off and Doxygen doesn't understand some Python features
(and tries to shoehorn others into C++ terminology), but other than
that, it serves us well.  We haven't tried epydoc yet.