Ok, so I"ve read both PEP 8 and PEP 257, and I"ve written lots of docstrings for functions and classes, but I"m a little unsure about what should go in a module docstring. I figured, at a minimum, it should document the functions and classes that the module exports, but I"ve also seen a few modules that list author names, copyright information, etc. Does anyone have an example of how a good python docstring should be structured?
Think about somebody doing
help(yourmodule) at the interactive interpreter"s prompt ‚Äî what do they want to know? (Other methods of extracting and displaying the information are roughly equivalent to
help in terms of amount of information). So if you have in
"""This module does blah blah.""" class Blah(object): """This class does blah blah."""
>>> import x; help(x)
Help on module x: NAME x - This module does blah blah. FILE /tmp/x.py CLASSES __builtin__.object Blah class Blah(__builtin__.object) | This class does blah blah. | | Data and other attributes defined here: | | __dict__ = <dictproxy object> | dictionary for instance variables (if defined) | | __weakref__ = <attribute "__weakref__" of "Blah" objects> | list of weak references to the object (if defined)
As you see, the detailed information on the classes (and functions too, though I"m not showing one here) is already included from those components" docstrings; the module"s own docstring should describe them very summarily (if at all) and rather concentrate on a concise summary of what the module as a whole can do for you, ideally with some doctested examples (just like functions and classes ideally should have doctested examples in their docstrings).
I don"t see how metadata such as author name and copyright / license helps the module"s user ‚Äî it can rather go in comments, since it could help somebody considering whether or not to reuse or modify the module.
Hands-On Machine Learning with Scikit-Learn, Keras, and TensorFlow: Concepts, Tools, and Techniques to Build Intelligent Systems PDF, 2nd Edition. This book assumes you know next to nothing about m...
This first edition of Strategic Engineering for Cloud Computing and Big Data Analytics focuses on addressing numerous and complex, inter-related issues which are inherently linked to systems engineeri...
Data is “unreasonably effective”. Nobel laureate Eugene Wigner referred to the unreasonable effectiveness of mathematics in the natural sciences. What is big data? Its sizes are in the order of te...
Efficiently perform data collection, wrangling, analysis, and visualization using Python. Recent advancements in computing and artificial intelligence have completely changed the way we understand ...