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

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?

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.

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?

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 :)