Default value in documentation
All, I'm starting to update the documentation of maskedarray to the latest standard. How should I represent the default value of an optional parameter ? I was thinking something like def function(a, value=None) """Does something *Parameters*: a : {ndarray} Input array. value : {float} *[None]* Some value. If None, a default based on the dtype of a is used. """" Suggestions/ideas are welcome. Thanks a lot in advance P.
Pierre GM wrote:
All, I'm starting to update the documentation of maskedarray to the latest standard. How should I represent the default value of an optional parameter ? I was thinking something like
def function(a, value=None) """Does something *Parameters*: a : {ndarray} Input array. value : {float} *[None]* Some value. If None, a default based on the dtype of a is used. """"
I prefer this: value : {float}, optional Some value. If not provided, a default based on the dtype of a is used. So label it optional and describe the default in prose in the parameter description if necessary. While this is less descriptive for meaningful defaults (axis=-1), the case you show above is precisely suited to it. None is not really the default value, it's really just being used as a marker for "argument not provided". And for the meaningful defaults, the function signature is more than adequate to provide the necessary information. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On Tuesday 02 October 2007 13:40:28 Robert Kern wrote:
I prefer this:
value : {float}, optional Some value. If not provided, a default based on the dtype of a is used. ... And for the meaningful defaults, the function signature is more than adequate to provide the necessary information.
OK, thanks a lot. Additional questions: is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ?
On Tue, 2 Oct 2007, Pierre GM apparently wrote:
is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ?
I thought it was ... :IVariables: i.e., I thought the standard was reST as handled by epydoc. <URL:http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines> <URL:http://epydoc.sourceforge.net/api/epydoc.markup.restructuredtext-module.html#CONSOLIDATED_DEFLIST_FIELDS> Cheers, Alan Isaac
On 10/2/07, Alan G Isaac <aisaac@american.edu> wrote:
On Tue, 2 Oct 2007, Pierre GM apparently wrote:
is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ?
I thought it was ... :IVariables: i.e., I thought the standard was reST as handled by epydoc. <URL:http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines> <URL: http://epydoc.sourceforge.net/api/epydoc.markup.restructuredtext-module.html...
We're avoiding consolidated fields because they behave badly. Chuck
On Tue, 2 Oct 2007, Charles R Harris apparently wrote:
We're avoiding consolidated fields because they behave badly. ... The main problem with the consolidated fields is that they are all put together as item lists in a definition list and moved to the end of the docstring when it is rendered. There is also little control through the .css style sheet, they are all bulleted, and some of the types are missing.
Is Ed Loper aware of this complaint? If so, has he indicated an interest (or lack) in addressing this complaint? Consolidated fields are great: it is a shame to do without them. Cheers, Alan Isaac
On Tuesday 02 October 2007 15:36:03 Alan G Isaac wrote:
On Tue, 2 Oct 2007, Pierre GM apparently wrote:
is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ?
I thought it was ... :IVariables: i.e., I thought the standard was reST as handled by epydoc. <URL:http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines> <URL:http://epydoc.sourceforge.net/api/epydoc.markup.restructuredtext-modul e.html#CONSOLIDATED_DEFLIST_FIELDS>
Mmh... That makes sense on one side, but it doesn't seem very consistent with the rest of the Numpy/Scipy standards... I'll stick to :IVariables: till a consensus is reached, then. Thanks again
Hi Pierre, On 10/2/07, Pierre GM <pgmdevlist@gmail.com> wrote:
On Tuesday 02 October 2007 15:36:03 Alan G Isaac wrote:
On Tue, 2 Oct 2007, Pierre GM apparently wrote:
is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ?
I thought it was ... :IVariables: i.e., I thought the standard was reST as handled by epydoc. <URL:http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines> <URL: http://epydoc.sourceforge.net/api/epydoc.markup.restructuredtext-modul e.html#CONSOLIDATED_DEFLIST_FIELDS>
Mmh... That makes sense on one side, but it doesn't seem very consistent with the rest of the Numpy/Scipy standards... I'll stick to :IVariables: till a consensus is reached, then. Thanks again ______
Umm, no, we don't use them in the standards anymore. You should look at the markup and run some examples. The main problem with the consolidated fields is that they are all put together as item lists in a definition list and moved to the end of the docstring when it is rendered. There is also little control through the .css style sheet, they are all bulleted, and some of the types are missing. This has been discussed on the list but few have shown much interest in the topic. The rendering of the current markup can be seen at http://www.scipy.org/doc/example/ Chuck
On 10/2/07, Robert Kern <robert.kern@gmail.com> wrote:
Pierre GM wrote:
All, I'm starting to update the documentation of maskedarray to the latest standard. How should I represent the default value of an optional parameter ? I was thinking something like
def function(a, value=None) """Does something *Parameters*: a : {ndarray} Input array. value : {float} *[None]* Some value. If None, a default based on the dtype of a is used. """"
I prefer this:
value : {float}, optional Some value. If not provided, a default based on the dtype of a is used.
So label it optional and describe the default in prose in the parameter description if necessary. While this is less descriptive for meaningful defaults (axis=-1), the case you show above is precisely suited to it. None is not really the default value, it's really just being used as a marker for "argument not provided". And for the meaningful defaults, the function signature is more than adequate to provide the necessary information.
I've been putting the default value first among the options. Thus axis : {-1, integer}, optional Chuck
On Tue, Oct 02, 2007 at 12:25:58PM -0600, Charles R Harris wrote:
So label it optional and describe the default in prose in the parameter description if necessary. While this is less descriptive for meaningful defaults (axis=-1), the case you show above is precisely suited to it. None is not really the default value, it's really just being used as a marker for "argument not provided". And for the meaningful defaults, the function signature is more than adequate to provide the necessary information.
I've been putting the default value first among the options. Thus
axis : {-1, integer}, optional
Since the default is already listed in the function signature, I would rather not duplicate it in the documentation. Stéfan
participants (5)
-
Alan G Isaac -
Charles R Harris -
Pierre GM -
Robert Kern -
Stefan van der Walt