[cctbxbb] Python documentation

[Luc Bourhis]

> I found one here after some random browsing: http://cctbx.sourceforge.net/current/python/rstbx.viewer.html, i.e.
> 
> get_intensities_in_box(self, x, y, boxsize=400, mag=16)
> # XXX does this need to be in C++?
> 
> which looks to me like it comes from rstbx/viewer/__init__.py.


The current code is

  # XXX does this need to be in C++?
  def get_intensities_in_box (self, x, y, boxsize=400, mag=16) :

I would not have thought that this comment would be picked up as if it was a docstring for that function.

> I don't suppose this is a problem, I'm just trying to understand what the rules are when the code is scraped for docs.

It is definitively not recommended to rely on that "feature" above: proper docstrings is the way to go. Ideally every module, every class, every function should have a docstring. For the functions, it should explain what are the arguments for  (especially if their name are not obvious), what types are ok. For classes, attributes that are public should be documented (I believe this can be done by adding a docstring after self.attr = ... in def __init__ but I am not 100% sure).

In practice, you will find this is rarely done. 

Luc

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20121008/21c6816b/attachment-0001.htm>