On Sun, Jul 14, 2013 at 8:01 PM, Cameron Simpson <c...@zip.com.au> wrote:
> On 15Jul2013 09:48, Steven D'Aprano <st...@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.
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
