More than 1 docstrings for a single module/function etc.?

Question

I'm using python 3.1.

Is it possible to create more than 1 docstring for a single module or function? I'm creating a program, and I'm intending to have multiple docstrings with a category for each. I intend to give other people the program so they can use it, and to make things easy for programmers and non-programmers alike, I'm putting a reference to the docstring for documentation within the program itself.

To be more specific, I have a menu in the program/module as an interface, and one of the options will allow access to the module docstring for documentation on the program. Thus, if it's possible, I want to make multiple docstrings to categorise different types of documentation. So it would be easier on the users if they want to see some part of the documentation.

eg. first docstring contains instructions on how to use the program. Second docstring contains information on how one part of the program works. Third docstring contains info on how another part works. etc.

Is this possible? And if so, how do you reference them?

Updates: Added a comment.

My original thought was to actually have more than one docstring in the sense of:

def foo():
    """docstring1: blah blah blah"""
    """docstring2: blah blah blah"""
    pass # Insert code here

Then there would be some code that I could use to allow me to reference each of these docstrings. So, I'm guessing that this isn't possible then?

Answer 1

I don't recommend trying to do something complicated with the docstrings. Best to keep the docstrings simple, and do something else if you want to make a bunch of different documentation options available.

If you really want to do what you described, I suggest you use tags to delimit sections within docstrings. Like so:

def foo(bar, baz):
    """Function foo()

* Summary:
    Function foo() handles all your foo-ish needs.  You pass in a bar and a baz and it foos them.

* Developers:
    When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests.

* Testers:
    When you test foo, be sure to try negative values for baz.
"""
    pass # code would go here

Then you can pretty easily split your string into chunks, and when the user chooses a menu item, show just the appropriate chunks.

s = foo.__doc__  # s now refers to the docstring

lst = s.split("\n* ")
section = [section for section in lst if section.startswith("Developers")][0]
print(section) # prints the "Developers" section

This way, when you are working in the interactive Python shell, you can say "help(foo)" and you will see all the docstrings. And, you are not changing the fundamental behavior of a basic part of Python, which would freak out other people trying to study your code.

You could also do something even simpler: just make a big global dictionary of docstrings for different purposes, and update it from the source code for each new thing.

doc_developers = {} doc_testers = {}

def foo(bar, baz):
    """Function foo()

Function foo() handles all your foo-ish needs.  You pass in a bar and a baz and it foos them."
    pass # code goes here

doc_developers["foo"] = "When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests."

doc_testers["foo"] = "When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests."

The biggest thing I don't like about this is that, if you change the name of function foo, you would need to change it in multiple places: once in the actual def and once per dictionary update line. But you could mostly fix that by writing a function:

def doc_dict = {} # this will be a dict of dicts
doc_dict["developers"] = {}
doc_dict["testers"] = {}

def doc_update(fn, d):
    name = fn.__name__
    for key, value in d.items():
        doc_dict[key][name] = value

def foo(bar, baz):
    """Function foo()

Function foo() handles all your foo-ish needs.  You pass in a bar and a baz and it foos them."
    pass # code goes here

d = { "developers": "When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests.",
"testers": " When you test foo, be sure to try negative values for baz."}

doc_update(foo, d)

There is probably a way to turn doc_update() into a decorator, but I'm out of time right now.

Answer 2

You want to consider using decorators to cleanly do what ~unutbu is proposing for functions: adding a separate field per each. For example:

def human_desc(description):
    def add_field(function):
        function.human_desc = description
        return function
    return add_field

This is what human_desc in action would look like:

@human_desc('This function eggfoobars its spam.')
def eggfoobar(spam):
    "Apply egg, foo and bar to our spam metaclass object stuff."
    print spam

---

Explaination

As the doc explains, that bit of code is equivalent to the following:

def eggfoobar(spam):
    "Apply egg, foo and bar to our spam metaclass object stuff."
    print spam
eggfoobar = human_desc('This function eggfoobars its spam.')(eggfoobar)

and human_desc('This function eggfoobars its spam.') returns the following function:

def add_field(function):
    function.human_desc = 'This function eggfoobars its spam.'
    return function

As you can see human_desc is a function that generates the above decorator for the value of description you pass as an argument. The decorator itself is a function that accepts a function to be decorated (modified) and returns it decorated (in this case, that is, with the addition of that bit of extra metadata). In short this is equivalent to:

def eggfoobar(spam):
    "Apply egg, foo and bar to our spam metaclass object stuff."
    print spam
eggfoobar.human_desc = 'This function eggfoobars its spam.'

The syntax, however, is far cleaner and less error prone.

Obviously, in either way, what you get is:

>>> print eggfoobar.human_desc
This function eggfoobars its spam.