[Doc-SIG] PEP-0216
Mark Hammond
MarkH@ActiveState.com
Sat, 11 Nov 2000 00:42:35 +1100
> Sure. I tried to give examples in my PEP which should be commited. As
> usual, the SF pages take a while to get updated (slow connection)
Yep - my mistake was following that hyperlink rather than looking at my file
system. The cost of convenience :-)
> Yes, something like that. Please have another look at the PEP and see if
> I managed to make myself clearer this time.
For our other readers:
---
a. A tag that means "this is a Python ``something'', guess what"
Example: In the sentence "The POP3 class", we need to markup "POP3"
so. The parser will be able to guess it is a class from the contents
of the poplib module, but we need to make it guess.
b. Tags that mean "this is a Python class/module/class var/instance
var..."
Example: In the sentence "This can be a regular file or a StringIO
object"
we need to markup "StringIO" as a Python class (the guesser might guess
it to be a module by mistake).
---
(a) I buy, but think it reasonable a convention could be to use parameters
around callable objects, and fully qualified names. Thus "module.variable",
"module.class", "local_class()", "local_function()" are all reasonable, and
within the structured text spirit (IMO). It only leaves "local_variable"
(or param, etc) requiring special treatment.
(b) I don't really buy - it appears the exact same problem to me. The
docstring should say "a regular file or a StringIO.StringIO() object". If
the user took you literally, and tried to create a "StringIO" object, it
would fail - presumably your module defines no such object.
Further, I believe it would be a reasonable policy decision for the
formatting tool to choose to *omit* both the module and the parens in the
final document if a link can be made - with the link there can be no
ambiguity. This gives you very pretty documentation, readable, clear
plain-text, and a pattern that will be correct the vast majority of cases.
Mark.