[Doc-SIG] Re: [Tutor] Documentation concerns. (LONG POST)
Jorge Godoy
godoy@metalab.unc.edu
Sun, 25 May 2003 17:31:19 -0300
Ian Bicking <ianb@colorstudy.com> writes:
> One issue I see with moving the documentation into the code, is that
> we don't have any system that can represent the kind of
> documentation from the standard library as docstrings. Typically
> documentation created from docstrings is highly (overly) structured,
> and does not allow items to be introduced in an order different from
> the code, or presented with a different structure than the code,
> plus there is no place for narrative that is not connected with a
> function or class.
On the other hand, putting an introductory text is possible.
I'm sorry for the long post, but I wished giving a simple example.
,----[ example.py ]----------------------------------------------------
#!/usr/bin/python -tt
#
# Demonstration file for everybody at python-tutor and crossposted
# people.
#
# $Author: $ (somebody@somewhere.overthe.net)
# $Date: $
#
# This is a demonstration on how introductory texts can be used to
# give better documentation, specially for newbies, including
# examples and an introductory text.
#
# All other docstrings can be maintained as they are.
#
# Note that I've included CVS keywords and an email for further
# contact on improving this module (or its documentation).
#
# Usage:
#
# import DemoClass
# checktemp = DemoClass(100, 'Celsius')
#
# # Here be functions to read the temperature from somewhere.
# # Lets suppose it was 89 Celsius degrees (water boils at 100
# # Celsius degrees)
# temperature = 89
#
# if checktemp.IsBoiling(temperature):
# print "Turn it off. It's boiling."
# else:
# print "Not ready yet."
#
#
# The rest of this document describes DemoClass' implementation. You
# should read it carefully to understand the above example and some
# other details.
# $Log: $
# Just an example of imported modules...
import os
import sys
class DemoClass:
"""
This is a demonstration class. It does nothing useful.
This demonstration class was written to show as an example of what
I had in my mind about a more complete documentation inside of
modules.
My main concern is with having usage example and a more complete
document than one with only the methods syntax and classes
available with (or inherited by) the module.
"""
def __init__(self, var = 'default', othervar = 'other default'):
"""
Initializes DemoClass and set values for 'var' and 'othervar'
DemoClass has 'default' as a default value for 'var', which
describes something in the system. It could be the default
temperature where the water boils.
'othervar', with a default value of 'other default' represent
something else. It could be the unit used to measure the
temperature (after all, we must know if we're working with
Celsius or Fahrenheit).
"""
self.var = var
self.othervar = othervar
def IsBoiling(self, temp_read):
"""
Checks if the water is boiling. Returns None if it isn't.
IsBoiling receives the read temperature. If it is the same
temperature that is available from self.var, it returns '1',
otherwise it returns None.
"""
if (temp_read == self.var):
return 1
else:
return None
def main():
"""
Main function for the program. Calls all other functions.
"""
checktemp = DemoClass(100, 'Celsius')
# Here be functions to read the temperature from somewhere.
# Lets suppose it was 89 Celsius degrees (water boils at 100
# Celsius degrees)
temperature = 89
if checktemp.IsBoiling(temperature):
print "Turn it off. It's boiling."
else:
print "Not ready yet."
if __name__ == '__main__':
main()
----------------------------------------------------------------------
The resulting output is:
,----[ pydoc ./example.py ]-------------------------------------------
Python Library Documentation: module example
NAME
example
FILE
/home/godoy/tempo/example.py
DESCRIPTION
# Demonstration file for everybody at python-tutor and crossposted
# people.
#
# $Author: $ (somebody@somewhere.overthe.net)
# $Date: $
#
# This is a demonstration on how introductory texts can be used to
# give better documentation, specially for newbies, including
# examples and an introductory text.
#
# All other docstrings can be maintained as they are.
#
# Note that I've included CVS keywords and an email for further
# contact on improving this module (or its documentation).
#
# Usage:
#
# import DemoClass
# checktemp = DemoClass(100, 'Celsius')
#
# # Here be functions to read the temperature from somewhere.
# # Lets suppose it was 89 Celsius degrees (water boils at 100
# # Celsius degrees)
# temperature = 89
#
# if checktemp.IsBoiling(temperature):
# print "Turn it off. It's boiling."
# else:
# print "Not ready yet."
#
#
# The rest of this document describes DemoClass' implementation. You
# should read it carefully to understand the above example and some
# other details.
CLASSES
DemoClass
class DemoClass
| This is a demonstration class. It does nothing useful.
|
| This demonstration class was written to show as an example of what
| I had in my mind about a more complete documentation inside of
| modules.
|
| My main concern is with having usage example and a more complete
| document than one with only the methods syntax and classes
| available with (or inherited by) the module.
|
| Methods defined here:
|
| IsBoiling(self, temp_read)
| Checks if the water is boiling. Returns None if it isn't.
|
| IsBoiling receives the read temperature. If it is the same
| temperature that is available from self.var, it returns '1',
| otherwise it returns None.
|
| __init__(self, var='default', othervar='other default')
| Initializes DemoClass and set values for 'var' and 'othervar'
|
| DemoClass has 'default' as a default value for 'var', which
| describes something in the system. It could be the default
| temperature where the water boils.
|
| 'othervar', with a default value of 'other default' represent
| something else. It could be the unit used to measure the
| temperature (after all, we must know if we're working with
| Celsius or Fahrenheit).
|
| ----------------------------------------------------------------------
| Data and non-method functions defined here:
|
| __doc__ = '\n This is a demonstration class. It does noth...availab...
|
| __module__ = 'example'
FUNCTIONS
main()
Main function for the program. Calls all other functions.
DATA
__file__ = './example.pyc'
__name__ = 'example'
----------------------------------------------------------------------
It seems to be too much documentation for such a small module, but it
helps a lot with big ones.
There are some modules that doesn't even generate an output when we do
'pydoc' on it (i.e., it has no docstrings at all), making it even
harder to use it (you have to go after its documentation on the
web). Of course, these aren't (up to now) included with Python in its
standard modules.
TIA,
--
Godoy. <godoy@metalab.unc.edu>