"""
This little script shows how you can write self documenting code
in Python.

S Babu:
joys of python: is a series of small and often silly scripts using
python that does something while explaining some nice features of
python. Absolutely newbie material.

http://vsbabu.org/mt/archives/categories/python/

All small values of joy are marked by comments starting with #joy:

References:
Python Styleguide http://www.python.org/doc/essays/styleguide.html
PyDoc http://web.lfw.org/python/pydoc.html 
PyFontify http://starship.python.net/~just/code/PyFontify.py
"""

__author__ = "S Babu <vsbabu_at_vsbabu_dot_org>"
__date__ = "09 September 2002"
__credits__ = """Guido van Rossum for an excellent programming language
Ka-Ping Yee for pydoc
"""
__version__ = "$Revision: 1.0$"
# $Source: /home/vsbabu/repository/python/joy/code_doc.py,v $

### Notes
#  If you use CVS/RCS, this is version and source are automatically
#  filled with proper values
#
#  Leave exactly one line before and one line after all that __XX__
#  stuff and the $Source.
#
#  The top level triple quotes string is the whole module/script's
#  documentation

#joy: very easy to make multiline strings without doing any character
#     escaping. Just enclose it in triple quoted strings.

#let us define a function that will be used globally
def global_function(s):
    """This is the global function. It can be called anywhere
    from the script
    
    It prints its argument"""
    
    print s


def print_code_documentation(f=None):
    """This just prints a given object's name and documentation
    
    If the object is none, it prints that of the current namespace
    """
    if f is not None:
        print f.__name__, ":\n", f.__doc__
    else:
        print __name__, ":\n", __doc__


class Vehicle:
    """A class that defines a vehicle
    
    Vehicle is anything that moves!
    """
    
    def __init__(self, name, wheels, capacity):
        """Constructor - creates a vehicle object
        
        name = what do you want to call the vehicle
        wheels = how many wheels does it have
        capacity = how many people can it carry
        """
        self.name = name
        self.wheels = wheels
        self.capacity = capacity
        return
        
    def show(self):
        """Just returns a string that shows the details"""
        return """%s - %d people on %d wheels""" % (self.name,\
            self.capacity,\
            self.wheels)
            

if __name__ == '__main__':
    #joy: if you run this script, the main module has the
    #name of __main__
    #makes it easy to add in your test conditions here.

    #print main doc
    print_code_documentation() 
    #print documentation for global_function
    print_code_documentation(global_function)
    #print documentation for itself!
    print_code_documentation(print_code_documentation)
    
    #let us print doc for a class
    print_code_documentation(Vehicle)
    #print it for specific method in the class
    print_code_documentation(Vehicle.show)
    
    #Ok, let us see if we can do something other than
    #printing code documentation
    mycar = Vehicle("Honda Accord 1994", 4, 5)
    print mycar.show()
    
    mycar.name = "Honda Accord 1994 DX"
    print mycar.show()
    
    #ok, now go and read http://www.python.org/doc/2.2/tut/node11.html