[cctbxbb] Docstrings and online reference

[Luc Bourhis]

Hi,

from somebody who's done that and been there several years ago…

> def set_u_iso(self, value = None, values = None, selection = None):
>  """Set isotropic mean thermic displacements of scatterers
> 
>  Input:
>  value -- (optional) a single double value to set all u_iso of selected 
> [...]
> 
>  Returns: cctbx.xray.structure
>  """

I would argue that the "(optional)" mention is completely redundant with the method declaration. In other commits, I saw you did

>   def __init__(self,
>         [...]
>         correct_rhombohedral_setting_if_necessary=False,
>         [...]
>       """
>         [...]
>      correct_rhombohedral_setting_if_necessary -- (optional, default=False) If set to 'True' an automatic conversion between rhombohedral and hexagonal basis will be done


Again the default=False is redundant.

It is already time-consuming enough to write and then maintain documentation: no need to increase the burden in such a manner.

Very valuable is the "Returns:" specification indeed and the mention of the actual type of objects. I admire your motivation and I would encourage you to continue if that does not distract you from whatever job you are paid for though. Indeed, eventually, you may have to choose between writing comments and writing productive code and we all know where the seesaw will swing!

>  [...]
> 
> During my first pass I noticed some already existing docstrings which are also 
> shown in the online docs at e.g.
> http://cctbx.sourceforge.net/current/python/cctbx.xray.structure.html.
> Are those pages automatically generated via a cronjob or does it take a manual 
> update to get this information up2date?

They are automatically generated using the documentation tools in Python standard library. When I set up for myself the task of commenting the cctbx many years ago, I tried to use a 3rd party tools producing better looking HTML but the experiment eventually died because of a lack of time. These days, I would advise you to try Sphinx. 

The idea is that the methods headers are automatically harvested by those documentation tools, along with the comment following each of them, and then that those tools interpret some markers in the comments to produce better output. Thus the comments should ideally use a marker language called reStructuredText, which has become universal in the Python world. I point you to Sphinx web page:
	http://sphinx.pocoo.org/
Note that sphinx is used for the official Python documentation itself.

Luc Bourhis


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20110210/2b3ca90c/attachment.htm>