Richard Jones' Log: Roundup API intro (and updated online reference)

Sun, 15 Feb 2004

A gentle introduction to the roundup API.Cool :)

I've recently run the roundup package through epydoc (having cleaned up the docstrings and defined __docformat__='restructuredtext') and it's pretty good. I've updated the API docs on the website with the results...

Comment by Mark Eichin on Sat, 17 Apr 2004

I was looking for examples of :param: in epydoc+rest, and found this - so I looked at the apidocs page, and found things like:

rawToHyperdb(db, klass, itemid, propname, value, pwre=<_sre.SRE_Pattern�object�at�0x4035ea70>)

That _sre.SRE_Pattern object bit is a glitch, right? some bug in the formatting processing?

Comment by Richard on Sat, 17 Apr 2004

Nope, the signature as given in the epydoc output is correct. What you're seeing there is a fairly common python hack.

The function in question uses a regular expression. Regular expressions are compiled at runtime, so to reduce the computing overhead of calling that function (and it's called a fair bit) I pre-compile the expression. Instead of shoving it into the module globals (which is slightly messier and slower) I have it shoved into the function locals by making it a keyword argument.

Comment by Mark Eichin on Sun, 18 Apr 2004

Ohh, the "static" trick. Hmm. In the docs, perhaps that deserves a :ptype pwre: static or something like that? (or even :param pwre: with the regexp used... or since it is hidden, doc it that way...) (Not criticizing your documentation, by the way, just trying to figure out reasonable conventions for mine, as I'm just getting started with epydoc+rest... and yes, I've already had a couple of cases where writing the docs for a function exposed a bug in it :-)

For that matter, should epydoc be clever enough to handle that case, possibly with an explicit hint (naming the param _pwre, even though python itself won't treat it differently, might make it clear that it isn't something the user is ever expected to override, so it might as well not be shown to them?

Comment by Richard on Mon, 19 Apr 2004

Even though it's not particularly pretty at the moment, I'm not sure that hiding the argument would be a good idea. I've not looked into the :param: stuff you're talking about, so I can't really comment on that :)