Hi all, as you might have noticed I started to add some docstrings to functions. The purpose of those is to give a user of the toolbox an idea of this: 1. What's the purpose of the object (function/method/class/...)? 2. What objects should be thrown at it as input/keyword arguments? 3. What kind of object does one get as return value? I try to extract the information only from the source code, so it's possible that I sometimes don't get it right, as I'm just starting to explore the inner workings of the toolbox and esp. phenix related parts are (yet) quite obscure for me. I'm trying to document objects in a consistent way, so that a user (as well as ourself) doesn't get confused. I invite you all to adapt the scheme for new functions/objects you code and request comments on further improving it before extending its use, so that it's useful and to your likeing as well. A current example of one such docstring: 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 scatterers to values -- (optional) an array of double values to set all u_iso of selected scatterers to selection -- (optional) an array of bools to select scatterers to be updated with new u_iso values Returns: cctbx.xray.structure """ [...] 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? Cheers, Jan
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
participants (2)
-
Jan Marten Simons -
Luc Bourhis