[Python-3000] Conventions for annotation consumers (was: Re: Draft pre-PEP: function annotations) (original) (raw)
Jim Jewett jimjjewett at gmail.com
Wed Aug 16 01:22:24 CEST 2006
- Previous message: [Python-3000] Conventions for annotation consumers (was: Re: Draft pre-PEP: function annotations)
- Next message: [Python-3000] Conventions for annotation consumers
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
On 8/15/06, Collin Winter <collinw at gmail.com> wrote:
... that users won't be using multiple type systems on the same parameter (and if they are, that their own problem); for "doc" is that a docstring is just a Python string, and there's really only own way to look at that within the scope of documentation strings.
oh ye of little cynicism.
(1) I might well restrict myself to a single type system. But that doesn't mean I don't ever want to use someone else's modules, or that I don't want a doc tool to handle them.
(2) doc strings already exist, and have already grown inconsistent microstructure.
"""one line summary -- may or may not include the call signature
Longer documentation, which may or may not also include doctests or ReST or html or sample calls in a non-doctest format or magic tokens used by various frameworks, such as Design By Contract wrappers.
Oh, and that first blank line? Some tools rely on it. Some functions don't use it.
Of course, some functions don't use docstrings at all, because the writers are already afraid that a framework like unittest will misinterpret them."""
-jJ
- Previous message: [Python-3000] Conventions for annotation consumers (was: Re: Draft pre-PEP: function annotations)
- Next message: [Python-3000] Conventions for annotation consumers
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]