On Sun, Jul 14, 2013 at 8:01 PM, Cameron Simpson <cs@zip.com.au> wrote:
On 15Jul2013 09:48, Steven D'Aprano <steve@pearwood.info> wrote: | On 14/07/13 21:09, Nick Coghlan wrote: | | >Slight adjustment to the proposed wording to ensure completely undocumented | >modules are also considered private: | | -1 on this adjustment. If somebody cannot be bothered writing a one-line doc string: | | "This module is private, don't touch." | | then they certainly shouldn't be allowed to use up a public name for a private module. I don't think we should be encouraging more private, undocumented modules. (Documentation is valuable even for private modules.) | | I'd go further, and say that no more private modules should be accepted for the std lib unless they have a leading underscore. I suppose for backwards compatibility reasons, we probably can't go through the std lib and rename private modules to make it clear they are private, but we don't have to accept new ones without the underscore.
I disagree.
A private module is a perfectly sane way to implement the internals of something, especially if it is subject to implementation change in the future.
Clarification: is Nick classifying a module with docstrings by no content in the "modules" section of the Python doco as undocumented?
Yes. This has nothing to do with docstrings, just the official documentation at docs.python.org.
That is what I would presume; I'd expect the code to be littered with docstrings anyway, but the module as a whole is not presented in the documentation and so should be private and not relied upon.
Exactly.