Standard way of documenting python code ?

Discussion in 'Python' started by Rony, Nov 28, 2003.

  1. Rony

    Rony Guest

    A question on python source documentation.
    Does there exist a standard for documenting code ?
    I've included here an example generated by pydoc of one of my modules.
    Is this the right way or is it overkill ?
    Comments are appreciated

    Thanks,

    Rony

    Help on module sqlquery:

    NAME
    sqlquery

    FILE
    m:\plymouth\sqlquery.py

    DESCRIPTION

    #########################################################################
    # Module : sqlquery.py
    # Abstract : General, simple, SQL class
    # Contains some simple classes
    # connection(connectstring): connect to db and define
    cursor
    # cmd(command,logflag=None) : execute sql-command
    # selcmd(dict,logflag=None) : execute select statement
    # inscmd(dict,logflag=None) : execute insert statement
    # Dependancies : mylibs.sqlerreur.py
    # mylibs.string_man.py

    #########################################################################

    CLASSES
    connection

    class connection
    | Connection to odbc source defined in connecstring
    | Public methods :
    | - close : close connection
    | - cmd : execute cmd and return result set
    |
    | Methods defined here:
    |
    | __init__(self, connectstring)
    | Create db connection from connectstring
    | Connect string must have the format 'odbc-source/user'
    | Will create cursor called self.cursor
    |
    | close(self)
    | Close database connection
    |
    | cmd(self, command, logresult=None)
    | Execute a SQL-statement, returns the resultset als list
    | if logresult != None then write result in log.txt
    |
    | inscmd(self, dict, logresult=None)
    | Execute a INSERT command.
    | The command is constructed out of a dictionary (dict)
    | The dict should contain :
    | "tocols" : list of destination cols as a string
    | "tables" : table where to insert as a string
    | "values" : list of values to insert as a string
    | Ex :
    | {'tocols':'AC_ID,AC_NOM',
    | 'table':'TBL_ACHETEUR',
    | 'values':'1,'+quote('RONY')}
    | will create : INSERT INTO TBL_ACHETEUR (AC_ID,AC_NOM)
    | VALUES(1,'RONY)
    | If logresult != None then write result in log.txt
    | Returns nothing
    |
    | selcmd(self, dict, logresult=None)
    | Execute a SELECT command.
    | The command is constructed out of a dictionary (dict)
    | The dict should contain :
    | "cols" : list of cols as a string
    | "tables" : list of tables as a string
    | "order" : list of orders as a string
    | Ex :
    | {'cols':'AC_ID,AC_NOM',
    | 'tables':'TBL_ACHETEUR',
    | 'order':'AC_ID'}
    | will create : SELECT AC_ID,AC_NOM FROM TBL_ACHETEUR
    | ORDER BY AC_ID
    | If logresult != None then write result in log.txt
    | Returns self.result

    DATA
    achtdict = {'cols': 'AC_ID,AC_NOM', 'order': 'AC_NOM', 'tables':
    'TBL_...
    connectstring = 'plymouth/sa/'
    insachdict = {'tables': 'TBL_TMP', 'tocols': 'TP_ID,TP_NOM',
    'values':...



    --
    Rony

    /_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
    /
    /
    | www.bucodi.com - My work
    \ www.ifrance/karamusique -- My hobby
    \_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
     
    Rony, Nov 28, 2003
    #1
    1. Advertising

  2. Rony

    John J. Lee Guest

    Rony <> writes:

    > A question on python source documentation.
    > Does there exist a standard for documenting code ?
    > I've included here an example generated by pydoc of one of my modules.
    > Is this the right way or is it overkill ?
    > Comments are appreciated

    [...]

    http://www.python.org/peps/pep-0008.html

    There are some good guidelines about docstrings in there.

    If you're writing in English, error is spelled "error", not
    "erreur". :)


    John
     
    John J. Lee, Nov 30, 2003
    #2
    1. Advertising

  3. Rony

    Rony Guest

    John J. Lee wrote on 30 Nov 2003 15:30:28 +0000 in : <>

    > Rony <> writes:
    >
    > > A question on python source documentation.
    > > Does there exist a standard for documenting code ?
    > > I've included here an example generated by pydoc of one of my modules.
    > > Is this the right way or is it overkill ?
    > > Comments are appreciated

    > [...]
    >
    > http://www.python.org/peps/pep-0008.html
    >
    > There are some good guidelines about docstrings in there.
    >
    > If you're writing in English, error is spelled "error", not
    > "erreur". :)
    >
    >
    > John


    Thanks for the link.
    Oh BTW 'erreur' of 'error' ? In both cases it won't be wrong , no? ;)


    --
    Rony

    /_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
    /
    /
    | www.bucodi.com - My work
    \ www.ifrance/karamusique -- My hobby
    \_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
     
    Rony, Dec 1, 2003
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Replies:
    0
    Views:
    634
  2. Andre Kostur

    Re: Documenting code in c++

    Andre Kostur, Jun 30, 2003, in forum: C++
    Replies:
    0
    Views:
    399
    Andre Kostur
    Jun 30, 2003
  3. Replies:
    5
    Views:
    429
    Cedric LEMAIRE
    Sep 3, 2003
  4. Jeff Rodriguez

    Documenting C Code

    Jeff Rodriguez, Nov 18, 2003, in forum: C Programming
    Replies:
    17
    Views:
    939
    CBFalconer
    Nov 20, 2003
  5. Isaac Rodriguez

    Documenting Python code.

    Isaac Rodriguez, May 3, 2005, in forum: Python
    Replies:
    5
    Views:
    5,549
    Fredrik Lundh
    May 5, 2005
Loading...

Share This Page