[Doc-SIG] PEP-0216

[Mark Hammond]

> 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.