[Python-Dev] docformat scope (original) (raw)

Guido van Rossum guido at python.org
Thu Apr 22 22:15:13 EDT 2004

Pep 258 [1] specifies that the docformat variable should be used to define the markup language used by docstrings in a module.

Recently, I got an RFE for epydoc requesting that a docformat in a package's init.py apply to the entire package [2]. My first reaction was that it was a good idea, but then I remembered a recent discussion on python-dev, where there seemed to be a strong sentiment that "from future import absoluteimport" should not have package scope [3]; and I wondered if some of the same arguments would go against applying docformat to the entire package. So... Should docformat have package scope (with submodules/ subpackages possibly overriding it), or should it only apply to the actual module that defines it? Either way, PEP 258 should be updated to reflect the decision.

The case isn't quite the same, but still, I think it would be better to be required to repeat this info in each module -- more explicit, and we know that explicit is better than implicit.

--Guido van Rossum (home page: http://www.python.org/~guido/)

More information about the Python-Dev mailing list