as per the title, I’m wondering: how accurate is the documentation returned when a package, module, function etc. is given as an argument to the help() builtin. I’ve never had any real issues with the documentation it provides, but it does always say at the top that it’s automatically generated and sometimes there is official documentation online that differs slightly.
For example, in tkinter, the documentation for the method tkinter.Misc.bind() is as follows:
bind(self, sequence=None, func=None, add=None)
However, if one checks the online documentation that to me seems to have been put together by an actual human (it doesn’t explicitly state this but it’s written in a very human voice - of course that doesn’t count for much these days, but I’m pretty sure it’s old enough to safely take it as an indication) it gives the syntax of the same tkinter.Misc.bind() method as:
def bind(self, sequence, func, add='')
Disregarding the def keyword in the second example, the first example seems to indicate that all the method’s local parameters are default parameters, and default to a value of None. The second example however (the one from the actual documentation) suggests that sequence and func are not default parameters at all and add defaults to an empty string.
perhaps '' == None, I don’t know, but what I do know is that .bind() can be called without passing anything in (it returns the events to which a handler has been bound for the widget on which it is called) which suggests that the automatically generated documentation is actually more correct(?)
as per the title, I’m wondering: how accurate is the documentation
returned when a package, module, function etc. is given as an argument
to the help() builtin. I’ve never had any real issues with the
documentation it provides, but it does always say at the top that it’s
automatically generated and sometimes there is official documentation
online that differs slightly.
They come from 2 different places.
When you say help(foo) you get:
the function signature derived from the def foo(.....) or
equivalent
the text from the docstring for foo
So if I define foo:
def foo(x, y=1):
''' Compute the sum of x and y (default 1). '''
return x + y
and consult help(foo):
>>> help(foo)
Help on function foo in module ds:
foo(x, y=1)
Compute the sum of x and y (default 1).
You can see the signature matches the def statement and the rest of
the help came from the docstring.
The formal documentation such as your tkinter.html example is usually
a separate document. So these may depart from each other.
Thanks, this is actually pretty simple. I went and looked at the source in tkinter and of course the actual function signature is as help() reports it.
I don’t know why the online documentation is different, I know an empty string is Falsy but surely it would have been more declarative to just set a default vale of add=False instead of add=''
The Misc.bind method has the conventional add=None signature so that
it uses None as a placeholder for “nothing specified, use the
default”.
The cmd construction above takes advantage of that to directly make
a '+' or '' to insert into the TCL command; any truthy value for add will result in a '+' and any falsey value for add will
result in ''. Grody, but working.
This is pretty old code, too, and the last change was 23 years ago. And
even that was just to remove TABs!
An interesting explanation, I find it pretty fascinating when I’m working with something and it turns out that some related code is ancient - I’d wager some of it could be older than me.
Imagine what it will be like in years to come, perhaps someone will dig up some old code that still powers something and realise it was written so long ago that the author is now dead and the code has been humming away for decades (of course it must happen even now, as you’ve just identified).
This is an unofficial mirror of Tkinter reference documentation
(based on Python 2.7 and Tk 8.5) created by the late John Shipman.
It was last updated in 2013 and is unmaintained. [More info]