[Tkinter-discuss] More thoughts on Tkinter documentation

Kenneth McDonald kmmcdonald at wisc.edu
Mon Mar 22 20:04:12 EST 2004


Here are two more ideas for how to proceed with Tkinter documentation.

1) Is it possible to set up some sort of "structured wiki", where
	a) Some people can set up documentation structure,
	and others can add to it.

	b) Anyone can go in and write documentation in a section,
	and the "owner" of the section can then integrate (or discard)
	what has been contributed.

For me, this would work well. If I needed to know something,
go look at the online document. If my answer is there, great.
If my answer isn't there, I have to go and figure it out myself--
and having done that, it isn't much more time to go back and
type in what I've found.

2) I'm still a big fan of inline documentation. However, I don't
really like docstrings because they don't provide enough
structure or analytical power, especially for a fairly complex
interface like Tkinter. I think it would be rather cool to define
a more structured form of inline documentation, eg. a __doct__
special field (combination of doc and dict) field, where, given a 
function

def f(foo, bar):
	....

The doct object for the function could be something like:

__doct__ = dict(
	args=dict(
		foo="This argument is never used.",
		bar="Neither is this one!"
	),
	return="Returns None or an integer",
	see=["otherfun1", "otherfun2"]
	examples = [...,...,...]
)

and so on. I like this for a number of reasons. It is easy to write
tools to check the validity of the documentation (i.e. are all arguments
described? Are any arguments described which don't actually
exist?). More importantly (at least in the short run), it would be
quite easy to write a little script which, given Tkinter documented
in this form, could nicely format and present the information
in the doct objects at various levels of detail. I could also conceive
of writing docts _outside_ of Tkinter (referring to the appropriate
methods/funs/etc by name), and then either include them
in Tkinter as a separate file, or write a script to do an automatic
integration. (There are definite advantages to the separate
approach, as long as it is done in a manner which allows tools
such as referred to above to work.)

As far as I'm concerned, the only thing that's preventing me
from contributing documentation right now is that I have no
structure to hang it on. I am embarrassed to confess that I
have never used CVS in any significant way (my background
is scripting/tech writing, not large project programming), and in any 
case
wouldn't want to go into Tkinter to do documentation without
a more structured approach than docstrings.

Any thoughts on the above? I can't do much about (1) myself,
but if I receive any positive feedback about (2), I'll put
together a couple of docts for a bit of Tkinter stuff, and post
them to see if people think its worth continuing.

Cheers,
Ken




More information about the Tkinter-discuss mailing list