[ENH] Module-level docstrings #567
Description
I learned something new from PEP 257, which is that you can return the docstring from a module, function, class, or method by calling the __doc__ special attribute.
For example:
import pandas
pandas.core.algorithms.__doc__
Out[3]: '\nGeneric data algorithms. This module is experimental at the moment and not\nintended for public consumption\n'
So, the motivation for this issue is that I think all the modules in this class have the same docstring:
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
But this won't be picked up by __doc__ since they need to be wrapped in triple quotes, so at a minimum we should make that change. This means any external tools trying to extract the docstring won't be able to pick up anything.
Second, this gives us an opportunity to maybe add something more descriptive than just the license. Since we already have a LICENSE file, I think we might be able to remove its mention from the individual modules, but then again due to actuaries' propensity for copying and pasting code from files maybe it's good to just leave it in. How about for starters we just add a brief description above/below the license after wrapping it in triple quotes?
This ticket will be done in conjunction with #486 as I work my way through the files but any of the new volunteers wishing to get ahead of me on this are welcome to do so.