Obviously this package is not python specific, and what I'm about to say is only useful for languages who treat documentation the same way as python, but! One

Obviously this package is not python specific, and what I'm about to say is only useful for languages who treat documentation the same way as python, but! One thing I like about python is that the documentation for any function or class is actually part of the object (held in its __doc__ attribute), and the whole 'triple-quoted string above the function' convention is actually just syntactic sugar, which assigns that string to the object's __doc__ attribute. The beauty of this is that you can completely externalise documentation into another package, if you really wanted to, and attach it to your objects separately! This means you can keep documentation separate, keeping your code as free of comments as you like. One nice thing about this, is that it allows you to maintain two 'categories' of documentation: the user-oriented documentation goes into the external file, whereas any 'developer-oriented' documentation which is explicitly for the maintainer's benefit while looking at the code, can appear directly in the source, and you can be sure that this will be safely removed from the user-oriented documentation later.