What is the proper way to comment functions in Python?

Question

Is there a generally accepted way to comment functions in Python? Is the following acceptable?

#########################################################
# Create         


        

Answer 1

I would go a step further than just saying "use a docstring". Pick a documentation generation tool, such as pydoc or epydoc (I use epydoc in pyparsing), and use the markup syntax recognized by that tool. Run that tool often while you are doing your development, to identify holes in your documentation. In fact, you might even benefit from writing the docstrings for the members of a class before implementing the class.