Re: Documenting a function signature

2015-06-18 Thread Ben Finney
Laura Creighton writes: > In a message of Thu, 18 Jun 2015 10:04:46 +1000, Ben Finney writes: > >Since the introduction of keyword-only arguments in Python functions, > >the question arises of how to communicate this in documentation. > > I suppose it is way too late to scream "I hate keyword-onl

Documenting a function signature (was: Set a flag on the function or a global?)

2015-06-17 Thread Ben Finney
Steven D'Aprano writes: > The full signature is: > > edir([object [, glob=''] [, dunders=True] [, meta=False]]) > > All four arguments are optional, and dunders and meta are > keyword-only. The official documentation seems to prefer this style:: edit(object, glob='', *, dunders=True, meta=F

Re: Documenting a function signature (was: Set a flag on the function or a global?)

2015-06-17 Thread Ian Kelly
On Wed, Jun 17, 2015 at 6:04 PM, Ben Finney wrote: > Steven D'Aprano writes: > >> The full signature is: >> >> edir([object [, glob=''] [, dunders=True] [, meta=False]]) >> >> All four arguments are optional, and dunders and meta are >> keyword-only. > > The official documentation seems to prefer

Re: Documenting a function signature (was: Set a flag on the function or a global?)

2015-06-17 Thread Chris Angelico
On Thu, Jun 18, 2015 at 10:04 AM, Ben Finney wrote: > Steven D'Aprano writes: > >> The full signature is: >> >> edir([object [, glob=''] [, dunders=True] [, meta=False]]) >> >> All four arguments are optional, and dunders and meta are >> keyword-only. > > The official documentation seems to prefe

Re: Documenting a function signature (was: Set a flag on the function or a global?)

2015-06-18 Thread random832
On Wed, Jun 17, 2015, at 20:14, Chris Angelico wrote: > Mostly. That would imply that object is a mandatory parameter, which > AIUI isn't the case for Steven's edir. The downside of this kind of > signature is that it's hard to show the parameters that have unusual > defaults (either sentinel objec

Re: Documenting a function signature (was: Set a flag on the function or a global?)

2015-06-18 Thread Laura Creighton
In a message of Thu, 18 Jun 2015 10:04:46 +1000, Ben Finney writes: >Since the introduction of keyword-only arguments in Python functions, >the question arises of how to communicate this in documentation. I suppose it is way too late to scream "I hate keyword-only arguments"! >The lone asterisk s