How to create a docstring for a module?

[Steven D'Aprano]

On Sun, 06 Dec 2009 10:55:50 +0100, Andreas Waldenburger wrote:

> On Sat, 5 Dec 2009 23:04:42 -0800 (PST) "Dr. Phillip M. Feldman"
> <pfeldman at verizon.net> wrote:
> 
> 
>> If I create a module xyz.py with a docstring """xyz does everything you
>> could possibly want.""" at the top, the command ?xyz issued at the
>> IPython prompt does not display this docstring.  What am I doing wrong?
> 
> Stab in the dark: You have imported the module first, right?
> 
> Also: Never, EVER, ask a question like this on any technical forum
> without posting your code (or rather: a minimal version of it that still
> exhibits the problem). That way, people can help you directly instead of
> taking wild guesses at what your problem might be.

In fairness, Phillip's description of the problem is pretty straight-
forward: he has a module xyz.py with a docstring. The minimal version of 
the code is no code at all, just a docstring:

"""xyz does everything you could possibly want."""

His problem isn't an error when running the code, but an error with 
IPython's command ?xyz.

What he didn't say is what IPython prints instead of the expected 
docstring. Over to you Phillip, don't just tell us what IPython doesn't 
do, tell us what it does do.

My guesses are:

* He hasn't imported the module, so he gets an error of some sort.

* He hasn't actually defined a docstring. Docstrings have to be string 
literals, you can't do this:

"""%s does everything you could possibly want.""" % "xyz"

Nor can you have anything except comments and whitespace between the top 
of the module and the string.

* He has another module called xyz which is shadowing the module he 
expects, and so he sees that module's docstring instead.


-- 
Steven