[Python-Dev] __docformat__ scope

[Guido van Rossum]

> 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 absolute_import" 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/)