Docstring style: should I really have it this long?

Question

I have a style question: this is specifically for Python, but it's something I've often wondered in other languages too.

I have an object that I'm returning all over the place: it's a dictionary with many keys. The main purpose of my module is one function returns this dictionary; the rest of the module is just implementation of this function. In the docstring for that main function I've helpfully documented exactly what the keys mean:

"""
Returns:
    None if the ROP should not be replaced, or a list of dictionaries
    corresponding to commands that should be run sequentially. Each
    dictionary contains the following keys:
        'command': a command that should be run in a shell
        'service': a string for the service that should be used, or None if any service can be used
        'cleanup_sequences': a list of hash-padded file sequences that should be cleaned up
        'cleanup_files': a list of files that should be cleaned up
        'log_sequences': a list of hash-padded file sequences that should be logged
        'log_files': a list of file that should be logged
        'start_frame': the first simulation frame / the first frame to be cleaned up
        'end_end': the last simulation frame / the last frame to be cleaned up
"""

Unfortunately for me, this object goes through three other functions before being returned by the main function in the module. I'm therefore including that whole blurb about the keys in each docstring for each of those three other functions.

That's not terrible in itself: but it's a lot of duplicated lines, and it's also a bunch of maintenance if I ever change the keys in this dictionary.

Have you guys come across this before? Since the keys are always the same, I'm wondering if I should wrap it in my own class "MyDictionaryClass" with its own docstring, and then in the docstrings for the functions I can just say "Returns: an instance of MyDictionaryClass". However, I'm not sure what kind of an object I should use---in C++ I'd probably typedef to some kind of named map.

Thanks for any advice Python gurus!

Answer 1

Not a guru but I had the same problem. I did indeed make my own dictionary:

class MyDictionary( dict ) :
    def __init__(self, *arg, **kwargs ):
        # do some stuff for instance check mandatory keys are present
        super(self.__class__, self).__init__( *arg, **kwargs )

Then I would doc string comment that my function return MyDictionary