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
