Re: [Tutor] doc string format ?
> I am trying to improve my code quality and have started using doc > strings. What format do you guys use for your doc strings ? > I have 'made up' the following general format ... > > def gen_vhost(kmotion_dir): >""" >Generate the kmotion vhost file from vhost_template expanding %directory% >strings to their full paths as defined in kmotion.rc > >arguments : >kmotion_dir ... the 'root' directory of kmotion > >exceptions: >exit ... if kmotion.rc cannot be read > >returns: >""" dave, excellent question and good to see that "you care" enough to ask. docstrings are one of Python's strengths, esp. given some of the external tools that are at your disposal. a) my 1st suggestion is to add some code to any of your docstrings where it makes sense; and even better would be some output. for example: def foo(x): """foo(x): display argument 'x' >>> foo(123) 123 """ print x this is helpful because if you're writing code for others (including yourself), it's easy to see what the proper syntax/usage is. b) given the above, wouldn't it be neat if there was a tool that could actually *execute* that code in your docstring as a regression test to (help) ensure code correctness? well, there is, and it's called the doctest module. if you add in the snippet below, you've just added testing for your code (and docstring)! def _test(): import doctest doctest.testmod() if __name__ == '__main__': _test() when you run your program, it should give no output if things ran swimmingly. if you do get output, that means that something went wrong. to see that it really works, just run your code with a "-v" flag: $ foo.py -v Trying: foo(123) Expecting: 123 ok 3 items had no tests: __main__ __main__.User __main__._test 1 items passed all tests: 1 tests in __main__.foo 1 tests in 4 items. 1 passed and 0 failed. Test passed. - the output tells you that of the 4 places that docstrings could go, only 1 had a test in a docstring (the other 3 didn't). c) on top of this, i would also 2nd kent's suggestion of using Epydoc, which is also compatible with doctest docstrings: http://epydoc.sourceforge.net/manual-epytext.html adding a bit more, you get this: def foo(x): """foo(x): display argument 'x' >>> foo(123) 123 @param x: this is the main arg for foo() @type x: 'x' can be any object, i.e., int, str, etc. @return: None since there is no explicit return """ print x now you can use Epydoc to generate HTML or PDF documentation of your entire code base! hope this helps! -- wesley - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - "Core Python Programming", Prentice Hall, (c)2007,2001 http://corepython.com wesley.j.chun :: wescpy-at-gmail.com python training and technical consulting cyberweb.consulting : silicon valley, ca http://cyberwebconsulting.com ___ Tutor maillist - Tutor@python.org http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] doc string format ?
> I am trying to improve my code quality and have started using doc > strings. What format do you guys use for your doc strings ? > I have 'made up' the following general format ... > > def gen_vhost(kmotion_dir): >""" >Generate the kmotion vhost file from vhost_template expanding %directory% >strings to their full paths as defined in kmotion.rc > >arguments : >kmotion_dir ... the 'root' directory of kmotion > >exceptions: >exit ... if kmotion.rc cannot be read > >returns: >""" dave, excellent question and good to see that "you care" enough to ask. docstrings are one of Python's strengths, esp. given some of the external tools that are at your disposal. a) my 1st suggestion is to add some code to any of your docstrings where it makes sense; and even better would be some output. for example: def foo(x): """foo(x): display argument 'x' >>> foo(123) 123 """ print x this is helpful because if you're writing code for others (including yourself), it's easy to see what the proper syntax/usage is. b) given the above, wouldn't it be neat if there was a tool that could actually *execute* that code in your docstring as a regression test to (help) ensure code correctness? well, there is, and it's called the doctest module. if you add in the snippet below, you've just added testing for your code (and docstring)! def _test(): import doctest doctest.testmod() if __name__ == '__main__': _test() when you run your program, it should give no output if things ran swimmingly. if you do get output, that means that something went wrong. to see that it really works, just run your code with a "-v" flag: $ foo.py -v Trying: foo(123) Expecting: 123 ok 3 items had no tests: __main__ __main__.User __main__._test 1 items passed all tests: 1 tests in __main__.foo 1 tests in 4 items. 1 passed and 0 failed. Test passed. - the output tells you that of the 4 places that docstrings could go, only 1 had a test in a docstring (the other 3 didn't). c) on top of this, i would also 2nd kent's suggestion of using Epydoc, which is also compatible with doctest docstrings: http://epydoc.sourceforge.net/manual-epytext.html adding a bit more, you get this: def foo(x): """foo(x): display argument 'x' >>> foo(123) 123 @param x: this is the main arg for foo() @type x: 'x' can be any object, i.e., int, str, etc. @return: None since there is no explicit return """ print x now you can use Epydoc to generate HTML or PDF documentation of your entire code base! hope this helps! -- wesley - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - "Core Python Programming", Prentice Hall, (c)2007,2001 http://corepython.com wesley.j.chun :: wescpy-at-gmail.com python training and technical consulting cyberweb.consulting : silicon valley, ca http://cyberwebconsulting.com ___ Tutor maillist - Tutor@python.org http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] doc string format ?
On Sun, June 8, 2008 1:54 am, dave selby wrote:
> Hi All,
>
>
> I am trying to improve my code quality and have started using doc
> strings. What format do you guys use for your doc strings ? I have 'made
> up' the following general format ...
Your made-up format looks good. It's great that you give thought to it.
I've seen the style-guide where it is suggested that the first line of the
doc string for a function is a very short description, starting with a
verb, like you did. That description should fit on one line.
Then there's a blank line.
Then there's the bigger explanation, calling instructions, return values,
exceptions raised, copyright notice, maybe.
A good thing is to type help("your_module") in the interpreter so that you
can see if you like the doc string and if it meshes nicely with what the
help facility provides for free.
But, mostly, I have to say that your instinct is good.
Marilyn Davis
>
> Cheers
>
>
> Dave
>
>
>
>
> def gen_vhost(kmotion_dir): """
> Generate the kmotion vhost file from vhost_template expanding %directory%
> strings to their full paths as defined in kmotion.rc
>
> arguments : kmotion_dir ... the 'root' directory of kmotion
>
> exceptions:
> exit ... if kmotion.rc cannot be read
>
> returns:
> """
> parser = ConfigParser.SafeConfigParser() parsed =
> parser.read('%s/core/kmotion.rc' % kmotion_dir) try:
> images_dbase_dir = parser.get('dirs', 'images_dbase_dir') port =
> parser.get('misc', 'port') LDAP_enabled = parser.get('LDAP', 'enabled') in
> ['true',
> 'True', 'yes', 'Yes']
> LDAP_url = parser.get('LDAP', 'AuthLDAPUrl')
> except (ConfigParser.NoSectionError, ConfigParser.NoOptionError):
>
> --
>
>
> Please avoid sending me Word or PowerPoint attachments.
> See http://www.gnu.org/philosophy/no-word-attachments.html
> ___
> Tutor maillist - Tutor@python.org
> http://mail.python.org/mailman/listinfo/tutor
___
Tutor maillist - Tutor@python.org
http://mail.python.org/mailman/listinfo/tutor
Re: [Tutor] doc string format ?
On Sun, Jun 8, 2008 at 4:54 AM, dave selby <[EMAIL PROTECTED]> wrote: > Hi All, > > I am trying to improve my code quality and have started using doc > strings. What format do you guys use for your doc strings ? PEP 257 has some general recommendations: http://www.python.org/dev/peps/pep-0257/ The standard library has lots of examples. > I have 'made up' the following general format ... >""" >Generate the kmotion vhost file from vhost_template expanding %directory% >strings to their full paths as defined in kmotion.rc > >arguments : >kmotion_dir ... the 'root' directory of kmotion > >exceptions: >exit ... if kmotion.rc cannot be read > >returns: >""" If you are going to use a structured format you might consider a format recognized by a documentation generator such as epydoc: http://epydoc.sourceforge.net/ http://epydoc.sourceforge.net/relatedprojects.html Kent ___ Tutor maillist - Tutor@python.org http://mail.python.org/mailman/listinfo/tutor
