[Doc-SIG] doc-sig/types-sig clash?

Edward Welbourne Edward Welbourne <eddyw@lsl.co.uk>
Tue, 4 Apr 2000 12:26:24 +0100 (BST)


> One of the proposals regarding typing seems to be inserting stuff into
> doc strings.

The doc-sig's current working scheme's keyword:ed hierarchical aspects
should make some kind of type-info expressible, which could be useful to
types-sig: but types-sig hasn't been presuming it particularly.  Its
mentions of doc-strings don't seem to presume anything dire (I think).

The main impact types-sig's current ideas are apt to have on doc-strings
is that there *may* be an extra place where one can add them.  Where a
module (or class) says that `this name in my namespace is to have that
type', there may also be scope for a doc-string saying `and here is what
I understand my attribute with that name as meaning' ... which would
mean we can separate this from the doc of the object in question (which
just says what the object does, regardless of who remembers it under
what name and what they will use it for), if we want.

decl reset:
    """Resets the module: platform-specific"""
    def() # This says: it's a func, takes no args, returns nothing

if os.name == 'nt':
    def reset():
        """Makes sure the registry knows we're available"""
        # one implementation

elif os.name == 'mac':
    def reset():
        """Nothing to do."""
	pass

elif os.name == 'posix':
    def reset():
        """Relaunches the daemon (kills old daemon if present)."""
        # another implementation

else:
    def reset():
        """Failure-implementation"""
        raise os.error, "I don't know how to reset() myself"

If it's any comfort, I'm a doc-sig regular being nosy about types-sig
and I don't see any conflicts between the two at present.  It might be
worth types-sig bearing in mind, however, that doc-sig now has a draft
spec (waiting for David to find some free time, which might have to wait
until the seasonal time-abyss has passed) which provides *scope for*
rich hierarchical data (anything XML could do, but written pythonically)
in the doc-string ... potentially describing arguments in rich detail ...
this could be interesting to those who want *static* type-information to
play with.  See:

    http://www.python.org/pipermail/doc-sig/

notably Nov and Dec 1999, notably things talking about `docstring
grammar', subject to the usual tendency for threads to meander relative
to their subject lines.  I don't remember a doc-sig decision about
*what* the `Argument:' section would contain, only that there surely
will be one and it wouldn't hurt for types-sig to be nosy about it.
Fortunately, I detect plenty of overlap between populations on these sigs.

> ... private sandbox.
Heh.
No, the whole mess is Gdo's sandbox, and he's made it public ;^)

	Eddy.