Python Coding/Documenting Style Question

Mahrt, Dallas dallasm at aiinet.com
Sun Jan 19 08:08:50 CET 2003


I would look into the Docutils project (http://docutils.sourceforge.net).
This project is attempting to provide a pluggable framework for documenting
Python code (including support for attributes). I believe they support
dcstrings for attributes. So the comment would be a string following the
definition of the attribute. (not sure about that). The docutils project has
also refined the suggested format for comments (PEP 257 (and 256 for
docutils specific))

> -----Original Message-----
> From: llothar at web.de [mailto:llothar at web.de] 
> Sent: Saturday, January 11, 2003 6:28 PM
> To: python-list at python.org
> Subject: Python Coding/Documenting Style Question
> 
> 
> Is there any common coding style for commenting variables
> like the following:
> 
> ====================================
> 
> globalVar = 666  # here comes a comment from hell
> 
> class foo:
> 	"This is the class comment"
> 		
> 	ClassVar = 10  # comment about this
> 	
> 	def __init__(self):
> 		self.objectVar = "foo"   # description of objectVar
> 		
> 		
> =====================================		
> 		
> It seems quite common to add the comments on the same line but.
> But what should i do when i want to use longer comments and/or 
> document the type of a variable. 
> 
> Is there any tool that can
> automatically generate documentation from such annotations ?
> -- 
> http://mail.python.org/mailman/listinfo/python-list
> 





More information about the Python-list mailing list