On Sun, Feb 12, 2012 at 2:45 AM, Isaac Morland <ijmor...@uwaterloo.ca> wrote: > Could the documentation generator simply insert the boilerplate if and only > if the package has the __provisional__ attribute? I'm not an expert in > Python documentation but isn't it generated from properly-formatted comments > within the Python source?
It can be, but, in the case of the standard library, generally isn't. While there's a certain attraction to using a __provisional__ attribute (checked by both Sphinx and pydoc) to standardise the boilerplate for provisional APIs, I don't think PEP 411 should be conditional on deciding *how* we implement the notices. It should just say "provisional APIs permit well justified changes that would otherwise be disallowed by backwards compatibility concerns, and these are the notices that must be put in place to indicate to users that an API is provisional". Whether we do that via copy-and-paste in the docs and docstring or by a flag in the source code is really an implementation detail separate from the process definition. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ 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
