On 9/22/2013 10:44 PM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy tjre...@udel.edu
('Return' rather than 'Returns' is the current convention.)
That's actually a religious argument which in the stdlib takes no strict
position -- a quick grep shows that both are
Am 23.09.2013 00:03, schrieb Guido van Rossum:
AFAIU, the proposal is to embed parts of the concise docstring into the
more
verbose .rst documentation.
I still think that's a bad idea. Someone editing the docstring may introduce a
terminology change or some other
On 23.09.13 17:18, Skip Montanaro wrote:
It would be great if the docstring contained a link to the online
documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
That *is* a feature of the help function:
Help on built-in module sys:
help(sys)
NAME
On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy tjre...@udel.edu
mailto:tjre...@udel.edu wrote:
I am gradually changing Idle docstrings, though only Idle
developers will ever see them. Writing a 60 char summary forces a
clear
On 22.09.13 16:34, Brett Cannon wrote:
The rule of thumb I go by is the docstring should be enough to answer
the question what args does this thing take and what does it do in
general to know it's the function I want and another one in the same
module? quickly and succinctly; i.e. just enough
On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald wal...@livinglogic.de wrote:
It would be great if the docstring contained a link to the online
documentation.
The docstring itself, or the presentation generated by help() ?
-Fred
--
Fred L. Drake, Jr.fred at fdrake.net
A storm broke
On 23.09.13 15:38, Fred Drake wrote:
On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald wal...@livinglogic.de wrote:
It would be great if the docstring contained a link to the online
documentation.
The docstring itself, or the presentation generated by help() ?
The presentation generated by
Le Mon, 23 Sep 2013 15:51:27 +0200,
Walter Dörwald wal...@livinglogic.de a écrit :
On 23.09.13 15:38, Fred Drake wrote:
On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald
wal...@livinglogic.de wrote:
It would be great if the docstring contained a link to the online
documentation.
The
On Mon, Sep 23, 2013 at 4:27 AM, Walter Dörwald wal...@livinglogic.dewrote:
It would be great if the docstring contained a link to the online
documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
--
--Guido van Rossum (python.org/~guido)
On Mon, Sep 23, 2013 at 12:57 AM, Larry Hastings la...@hastings.org wrote:
On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy tjre...@udel.edu wrote:
I am gradually changing Idle docstrings, though only Idle developers will
ever see them. Writing
On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum gu...@python.org wrote:
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel python-...@masklinn.netwrote:
The points here are that there's a single source of truth (so we can't
have conflicting docstring and rst documentation), and
On Mon, 23 Sep 2013 08:57:01 +0100
Larry Hastings la...@hastings.org wrote:
On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy tjre...@udel.edu
mailto:tjre...@udel.edu wrote:
I am gradually changing Idle docstrings, though only Idle
It would be great if the docstring contained a link to the online
documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
That *is* a feature of the help function:
Help on built-in module sys:
help(sys)
NAME
sys
FILE
(built-in)
MODULE DOCS
On 09/23/2013 04:43 PM, R. David Murray wrote:
On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum gu...@python.org wrote:
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel python-...@masklinn.netwrote:
The points here are that there's a single source of truth (so we can't
have conflicting
On 9/23/2013 11:18 AM, Skip Montanaro wrote:
It would be great if the docstring contained a link to the online
documentation.
That would have to be a feature of help(), not hardcoded in each docstring.
That *is* a feature of the help function:
Help on built-in module sys:
help(sys)
NAME
On 9/23/2013 10:56 AM, Guido van Rossum wrote:
I think 60 is just a guideline. In stdlib .py source code I want it not
to extend beyond the 79th column (see recent PEP 8 argument). For a
PEP 8 says Limit all lines to a maximum of 79 characters.
For flowing long blocks of text with fewer
On Mon, Sep 23, 2013 at 10:52 AM, Terry Reedy tjre...@udel.edu wrote:
On 9/23/2013 10:56 AM, Guido van Rossum wrote:
I think 60 is just a guideline. In stdlib .py source code I want it not
to extend beyond the 79th column (see recent PEP 8 argument). For a
PEP 8 says Limit all lines to a
On 9/22/2013 10:44 PM, Guido van Rossum wrote:
Glad you like it. I still do, too, but I've given up hope to convince
all core developers to stick to this style. :-(
[me] ('Return' rather than 'Returns' is the current convention.)
That's actually a religious argument which in the stdlib
On 23/09/2013 20:01, Terry Reedy wrote:
On 9/22/2013 10:44 PM, Guido van Rossum wrote:
Glad you like it. I still do, too, but I've given up hope to convince
all core developers to stick to this style. :-(
[me] ('Return' rather than 'Returns' is the current convention.)
That's actually a
On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy tjre...@udel.edu wrote:
IIRC in the Java world you *have* to
use 'Returns', but I don't buy the argument from nit-picky grammarians
that leads to this rule. (It's something about the documentation not
being a command. But English is more flexible
On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy tjre...@udel.edu wrote:
'Return' versus 'Returns', exact uppercase word match, is a little over 3 to
1. I am sure I have seen 'Return' and similiar directive forms ('Print',
'Store', 'Compare', etc) recommended as current doc style, as prefered by
This is getting off-topic, if you're not interested in English grammar
you should stop reading.
On Mon, Sep 23, 2013 at 03:18:01PM -0400, Alexander Belopolsky wrote:
I don't think Returns bar. is a valid English sentence because it lacks
subject.
Subjectless sentences are unusual in
Given near-consensus on the Return ... form, the following discussion is
of academic interest only.
On Mon, Sep 23, 2013 at 9:31 PM, Steven D'Aprano st...@pearwood.infowrote:
I would not mind
def foo():
returns bar
which I would read as Function foo() returns bar, but in this
I don't like having to browse the source code to read the documentation. I
prefer short docstring and longer reST documentation. In ReST, you get a
table of content and nice links to functions, modules, etc.
When I read doc, I like having two levels: tutorial listing most important
functions and
On Sun, 22 Sep 2013 13:13:04 +1000
Steven D'Aprano st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment, I have extensive
docstrings in the module itself. I don't believe anyone has flagged that
On 09/22/2013 05:13 AM, Steven D'Aprano wrote:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment, I have extensive
docstrings in the module itself. I don't believe anyone has flagged that
as too much information in a
On 22 September 2013 18:54, Georg Brandl g.bra...@gmx.net wrote:
I don't really buy the argument but then there is no complete documentation
set in the checkout -- who reads that in preference to docs.python.org?
And if anybody does want plain-text docs, they are already available for build
On 2013-09-22, at 12:16 , Nick Coghlan wrote:
It's a bit of a pain, and we do occasionally get bug reports where the
docstrings get out of date, but it's the least bad of the currently
available options.
Is it really less bad than allowing limited fine-grained use of autodoc?
Not necessarily
On 09/22/2013 12:16 PM, Nick Coghlan wrote:
On 22 September 2013 18:54, Georg Brandl g.bra...@gmx.net wrote:
I don't really buy the argument but then there is no complete documentation
set in the checkout -- who reads that in preference to docs.python.org?
And if anybody does want plain-text
On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote:
On Sun, 22 Sep 2013 13:13:04 +1000
Steven D'Aprano st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment, I have extensive
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano st...@pearwood.infowrote:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment, I have extensive
docstrings in the module itself. I don't believe anyone has flagged that
as
On 09/22/2013 02:54 PM, Eli Bendersky wrote:
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano st...@pearwood.info
mailto:st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment,
On 22 September 2013 13:54, Eli Bendersky eli...@gmail.com wrote:
IMHO the right way to think about it is that the .rst files are by far the
more important documentation. Sometimes we forget that most Python
programmers are people who won't go into the source to read docstrings.
While I agree
On Sun, Sep 22, 2013 at 6:06 AM, Georg Brandl g.bra...@gmx.net wrote:
On 09/22/2013 02:54 PM, Eli Bendersky wrote:
On Sat, Sep 21, 2013 at 8:13 PM, Steven D'Aprano st...@pearwood.info
mailto:st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage
On 23 September 2013 00:16, Eli Bendersky eli...@gmail.com wrote:
That's a good point. I would still posit that HTML documentation gets by far
the most use, but docstrings are definitely important too. One more point in
favor of either:
1. Maintaining both, as tiresome as it is (we try to do
On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano st...@pearwood.infowrote:
On Sun, Sep 22, 2013 at 10:20:46AM +0200, Antoine Pitrou wrote:
On Sun, 22 Sep 2013 13:13:04 +1000
Steven D'Aprano st...@pearwood.info wrote:
Hi all,
I have a question about how I should manage documentation
On 22 Sep 2013, at 05:25, Benjamin Peterson benja...@python.org wrote:
There's not really much to do but maintain them separately. Truncate
the docstrings if it makes life easier.
Autodoc could be enabled and allowed in a limited manner.
___
On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote:
The rule of thumb I go by is the docstring should be enough to answer the
question what args does this thing take and what does it do in general to
know it's the function I want and another one in the same module? quickly
and succinctly; i.e. just
On Sun, Sep 22, 2013 at 8:49 AM, Barry Warsaw ba...@python.org wrote:
On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote:
The rule of thumb I go by is the docstring should be enough to answer the
question what args does this thing take and what does it do in general to
know it's the function I
Eli Bendersky writes:
IMHO the right way to think about it is that the .rst files are by
far the more important documentation. Sometimes we forget that
most Python programmers are people who won't go into the source
Why source? The whole point of docstrings is that they are *not*
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull step...@xemacs.orgwrote:
Eli Bendersky writes:
IMHO the right way to think about it is that the .rst files are by
far the more important documentation. Sometimes we forget that
most Python programmers are people who won't go into
On Sun, Sep 22, 2013 at 10:07 AM, Guido van Rossum gu...@python.org wrote:
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull
step...@xemacs.orgwrote:
Eli Bendersky writes:
IMHO the right way to think about it is that the .rst files are by
far the more important documentation.
On 09/22/2013 08:49 AM, Barry Warsaw wrote:
On Sep 22, 2013, at 10:34 AM, Brett Cannon wrote:
The rule of thumb I go by is the docstring should be enough to answer the
question what args does this thing take and what does it do in general to
know it's the function I want and another one in the
On 9/22/2013 10:25 AM, Nick Coghlan wrote:
As Georg noted, we'd have to do some fancy footwork to make sure
autodoc didn't pick up the wrong module versions for the standard
library docs, though.
Is that a one-time nuisance, a per-module nuisance, a per-autodoc-use
nuisance, or a per-build
-Dev [mailto:python-dev-bounces+anikom15=gmail@python.org] On
Behalf Of Brett Cannon
Sent: Sunday, September 22, 2013 7:34 AM
To: Steven D'Aprano
Cc: python-dev
Subject: Re: [Python-Dev] Best practice for documentation for std lib
On Sun, Sep 22, 2013 at 8:53 AM, Steven D'Aprano st
On Sun, Sep 22, 2013 at 11:02 AM, Westley Martínez aniko...@gmail.comwrote:
Since help() is usually the first thing I use to remind myself of an
API, it's imperative that the doc strings are up to date and make sense
to end users.
So, autogeneration of doc strings would be good for someone
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky eli...@gmail.com wrote:
I think there's a general agreement in this thread that we don't intend to
change the status quo. Both .rst docs and docstrings are important. The
remaining question is - can we use some tool to generates parts of the
On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum gu...@python.org wrote:
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky eli...@gmail.com wrote:
I think there's a general agreement in this thread that we don't intend
to change the status quo. Both .rst docs and docstrings are important.
From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido
van Rossum
Sent: Sunday, September 22, 2013 11:35 AM
You seem to misunderstand the use of autogeneration. It refers to generating
the .rst docs from the docstrings in the source. And FWIW, I'm against that
On 2013-09-22, at 21:24 , Westley Martínez wrote:
From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido
van Rossum
Sent: Sunday, September 22, 2013 11:35 AM
You seem to misunderstand the use of autogeneration. It refers to
generating
the .rst docs from the
practice for documentation for std lib
On 2013-09-22, at 21:24 , Westley Martínez wrote:
From: gvanros...@gmail.com [mailto:gvanros...@gmail.com] On Behalf Of Guido
van Rossum
Sent: Sunday, September 22, 2013 11:35 AM
You seem to misunderstand the use of autogeneration. It refers
On Sun, Sep 22, 2013 at 11:44 AM, Eli Bendersky eli...@gmail.com wrote:
On Sun, Sep 22, 2013 at 11:40 AM, Guido van Rossum gu...@python.orgwrote:
On Sun, Sep 22, 2013 at 10:25 AM, Eli Bendersky eli...@gmail.com wrote:
I think there's a general agreement in this thread that we don't intend
On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel python-...@masklinn.netwrote:
The points here are that there's a single source of truth (so we can't
have conflicting docstring and rst documentation), and documentation
becoming outdated can be noticed from both docstring and published
On Sun, Sep 22, 2013 at 05:54:57AM -0700, Eli Bendersky wrote:
IMHO the right way to think about it is that the .rst files are by far the
more important documentation. Sometimes we forget that most Python
programmers are people who won't go into the source to read docstrings.
Docstrings are
On Sun, Sep 22, 2013 at 5:07 PM, Steven D'Aprano st...@pearwood.infowrote:
If you're going to the source to read docstrings, you're doing it wrong
:-)
Be that as it may, when I'm reading the source I'm grateful for docstrings.
*And* I'm grateful when they are short.
--
--Guido van Rossum
On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote:
Authors writing 3rd party packages can do what they want.
But for the stdlib it's been settled for ages: docstrings should be concise
(but not cryptic(*)), longer documentation go into the separately written
text for
On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano st...@pearwood.infowrote:
On Sun, Sep 22, 2013 at 10:07:28AM -0700, Guido van Rossum wrote:
Authors writing 3rd party packages can do what they want.
But for the stdlib it's been settled for ages: docstrings should be
concise
(but not
On 9/22/2013 10:04 PM, Guido van Rossum wrote:
If I had the final word, I'd recommend using the current docstrings as
the .rst contents and replacing the docstrings with the 1-2 line
function descriptions from the PEP, e.g.:
* median(data) - median (middle value) of data, taking
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy tjre...@udel.edu wrote:
On 9/22/2013 10:04 PM, Guido van Rossum wrote:
If I had the final word, I'd recommend using the current docstrings as
the .rst contents and replacing the docstrings with the 1-2 line
function descriptions from the PEP,
Guido van Rossum writes:
On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano st...@pearwood.info wrote:
My own preference is to err on the side of too much rather than
too little, since I live by help() and only fall back on the web
documentation when I really must.
I guess preferences
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment, I have extensive
docstrings in the module itself. I don't believe anyone has flagged that
as too much information in a code review, so I'm going to assume that
large
There's not really much to do but maintain them separately. Truncate
the docstrings if it makes life easier.
2013/9/21 Steven D'Aprano st...@pearwood.info:
Hi all,
I have a question about how I should manage documentation for the
statistics module for Python 3.4. At the moment, I have
62 matches
Mail list logo
