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

You can replace the __doc__ attribute if you want to have more than one possible docstring, but please consider making the initial docstring flexible enough for all types.

Answer 2

Module is a collection of classes/functions/modules. So its docstring gives the intro about what it contains.

Class docstring tells what the class is about and its methods docstrings tell what the methods so. A class serves one purpose and a methods does a single thing so they should have single docstring.

Functions do one thing so one doctring should suffice for them.

I can't see what purpose will multiple docstrings suffice. Maybe your module is big. Divide into sub-modules and in the docstring for the module mention sub-modules.

Answer 3

Instead of using a function, you could use a class with usage and extra attributes defined. For example,

class Foo(object):
    '''Here is the function's official docstring'''
    usage='All about the usage'
    extra='How another part works'
    def __call__(self):
        # Put the foo function code here
        pass
foo=Foo()

You'd call it as usual: foo(), and you can get the official docstring, and alternate doc string like this:

print foo.__doc__
print foo.usage
print foo.extra

You can also attach extra attributes to plain functions (instead of using a class as I did above), but I think the syntax is a little uglier:

def foo():
    pass
foo.usage='Usage string'
foo.extra='Extra string'

And, modules are objects too. They can have extra attributes just as easily:

If you define module constants

USAGE='''blah blah'''
EXTRA='''meow'''

Then when you import the module:

import mymodule

You can access the official and alternate docstrings with

mymodule.__doc__
mymodule.USAGE
mymodule.EXTRA

Answer 4

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 5

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.