[capi-sig] Documenting a C/Py API

[Campbell Barton]

Hi Guys,
first post on the list, dont be shy ;)

In Blender3D were doing an API refactor and Im looking at better ways to 
  write the Python C/API documentation.

At the moment we use epydoc, Its all Iv used so I don't have much to 
compare it to.

If you havnt used it, its basically a way to add formatting to your 
normal .py docstrings so they can be converted into HTML or PDF.

This works well with python only projects but is not somthing you can do 
in C without some manual docstring extraction from the C/API.

for blender3d we have C doctrings as well as python files that just 
contain functions with docstrings (no actual code) for epydoc to write 
them to html.

The C/API docstings often end up being brief and not that helpful, since 
the epydocs are what most people use so more effort is put there.

Here are the current epydocs.
http://www.blender.org/documentation/244PythonDoc/index.html




Ideally Id like to only maintain 1 set of docs... so possibilities are
1) dont write epydocs, only use docstrings (we need a way we can browse 
them as HTML still)

2) dont write C API/docstrings, just have empty strings where all the 
docstrings would go.

3) include epydoc formatting in C API/docstrings and pass these 
docstrings to epydoc for it to generate HTML.


Iv got 3) working as a testcase, the message attached details how this 
works with the pro's and con's of adding epydoc tags into C/API docstrings.

However Id be interested to know how other projects deal with the issue 
of maintaining docstrings and online docs.

Cheers