[capi-sig] Documenting a C/Py API

[Campbell Barton]

Martin Poirier wrote:
> --- Carsten Haese <carsten at uniqsys.com> wrote:
> 
>> On Mon, 2007-07-02 at 23:30 +1000, Campbell Barton
>> wrote:
>>> However Id be interested to know how other
>> projects deal with the issue 
>>> of maintaining docstrings and online docs.
>> I maintain separate docstrings and online docs for
>> one simple reason:
>> The online docs can be more extensive than
>> docstrings. Docstrings are
>> for brief memory-joggers. Online documentation can
>> contain examples and
>> generally more detail that's not appropriate for
>> docstrings.
> 
> Can you elaborate on this a bit. What kind of tools do
> you use to generate/maintain your docs?
> 
> Martin
> 
> - Blender developer

Its just one script that runs inside blender and writes its docstrings 
to py files epydoc can use.

http://projects.blender.org/plugins/scmsvn/viewcvs.php/branches/pyapi_devel/source/blender/python/api2_2x/doc/_epy_write_docstrings.py?view=markup&root=bf-blender&pathrev=11145

At the moment it just takes a PyType, and writes a file with its methods 
and attributes. adding indenting and method names to the epydocs.

I wrote this last night and it only works with the Group and Camera 
types, so if we choose to keep using this method we can extend and 
modify as needed.



Barry pointed out that docs could be generated with epydoc inspecting 
the C api directly,
Id be interested to know if you had much epydoc spesific stuff in these 
docstrings, though i was aware this was possible in some cases, you end 
up with nicer docs if they include formatting tags.

Carsten, agree Examples within the C docstrings is bloating them too 
much, Id like to add these in when generating the py files with some 
form of #include that inserts an existing Py file.


Thanks for your feedback - I may be over reacting about maintaining 2 
sets of docstrings because when I first started with Blenders Python api 
there would be for instance..
  mesh.getName()
  mesh.setName()
  mesh.name

And each needed a docstring and epydoc, so we had to have 6 different 
bits of documentation for each setting. We have decided not to use 
get/set style anymore so its only 2 - which may be a necessary annoyance 
and not that bad in practice.

This is the biggest PyType we have, to get an idea of what Im talking 
about...

file:///cvs_blender/blender/source/blender/python/api2_2x/doc/BPY_API/Object.Object-class.html