Should use docstrings to document units
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
python-quantities |
Fix Released
|
Medium
|
Darren Dale |
Bug Description
You should use docstrings in the unit and constant definitions for each unit, to provide helpful text instead of just leaving it in the source code comments. In IPython, for instance, you can see the (example) docstring very easily:
In [17]: quantities.au?
Type: UnitLength
Base Class: <class 'quantities.
String Form: 1 au (astronomical_unit)
Namespace: Interactive
File: /usr/local/
Docstring:
An astronomical unit (abbreviated as AU, au, a.u., or sometimes ua) is a
unit of length roughly equal to the mean distance between the Earth and
the Sun. It is approximately 150 million kilometres (93 million miles).
See http://
description: | updated |
Changed in python-quantities: | |
milestone: | none → 0.5.0 |
Changed in python-quantities: | |
status: | Fix Committed → Fix Released |
Thanks for the suggestion. I added a doc kwarg to set the __doc__ attribute for instances of UnitQuantity and subclasses thereof. It looks like python's built-in help ignores the instance and inspects the class itself, I don't think there is anything I can do about that.
I converted what comments and notes were already in place, but the majority of the units and constants are undocumented at this point.
If anyone wants to submit patches for documentation, please feel free to do so, but please be sure to cite your references, preferably using an authority like NIST or IUPAC if available, or wikipedia. Patches that do not include citations will not be accepted, however.