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
