Docstrings

[Tim Peters]

[Gerrit Holl]
> But I want some sort of definition: what types may contain doc
> strings?

You're not getting a defn simply because there isn't one.  If you want to
know whether a thing t has a docstring,

    hasattr(t, "__doc__")

is the certain and foolproof way to figure it out.  Or, probably better in
practice:

    doc = getattr(t, "__doc__", None)
    if doc is not None:
        if type(doc) is not type(""):
            doc = str(doc)
        # now do something with doc

This is the paranoid way, weeding out objects that do have a __doc__
attribute but set it to None, and catering to objects that store *some*
(possibly non-string) non-None object in their __doc__ attribute that
nevertheless supports str()-ification.

> Strings, lists, dictionaries and all numeric types obviously may not.

That's a bad assumption; there's nothing to prevent adding a __doc__
attribute to objects of these types in the future, and, indeed, that might
even be nice!

>>> print math.e.__doc__
Base of natural logarithms = 2.718281828...
>>>

I doubt Python will actually do that (it has added __doc__ attrs to other
object types over the years), but there's no "theoretical" reason not to.

timbot.__doc__=="ly y'rs  - tim"-ly y'rs  - tim