Improve code documentation

[tschoppi]

The code is slowly starting to get properly documented with docstrings (see here the relevant PEP 257).

Whenever new unit tests are written (see issue #29) the docstrings should also be added to the code base. These tasks go hand in hand, as both have the potential to uncover hidden logical flaws in the design as it currently stands.

[tschoppi]

Maybe @MyrionPhoenixmoon can elaborate on the format we should use for the docstrings?

[MyrionPhoenixmoon]

I think we should use a docstring format that integrates as easily as possible with tooling. I use PyCharm as my IDE, and it uses a docstring format that Sphinx-Doc (a documentation generator) understands, so I suggest we use that.

Example:

def someMethod(self, arg1, arg2) -> Any:
"""
This explains, on one line, what someMethod does.
:param arg1: This explains what arg1 should be, what happens to it, etc.
:param arg2: It does not hint at types, though.
:type arg1: This is for type hinting!
:type arg2: For all params, of course.
:return: Explains the return value. 
"""

Of course, not all methods require extensive docstrings. starsystem.random_age(), for example has the following docstring:

"""
Randomly determines the age of the star system in billions of years.
:return: An int factor of billion years.
"""

However, wherever a method has parameters, at least type hinting should be provided, and ideally the params are all documented, so we can provide an autogenerated documentation.

[tschoppi]

Do we put empty lines between the summary line and the detailed description, as outlined by PEP 257?

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.

I personally think that makes it more easily readable for humans, even if the software doesn't care.

[MyrionPhoenixmoon]

Only if we have a more detailed explanation, I'd say. I dislike the empty line there if there isn't more text afterwards. The :param lines are different enough for me to be easily distinguishable and readable.

[tschoppi]

I think it's nicer to separate the information in the docstrings into blocks: First the "title" or summary, then the parameters and return value descriptions, and thirdly the in-depth description of what that function/class does. These blocks should be separated by blank lines.

Example:

def someMethod(self, arg1, arg2) -> Any:
"""
This explains, on one line, what someMethod does.

:param arg1: This explains what arg1 should be, what happens to it, etc.
:param arg2: It does not hint at types, though.
:type arg1: This is for type hinting!
:type arg2: For all params, of course.
:return: Explains the return value. 

This is a longer explanation of what someMethod accomplishes, which can also be
split onto several lines. Hard wrapping the lines may be considered, a width of 
80 characters, the standard terminal width, is proposed.
"""

[MyrionPhoenixmoon]

Alright, you've convinced me. Let's do it that way.

We should probably put this example into the ReadMe under "Documentation", to make it clear to outsiders wanting to join that this is the preferred docstyle.

[tschoppi]

I wrote a wiki article where this is mentioned. I don't think it really belongs in the README.

[MyrionPhoenixmoon]

Ah, yes, much better. I forgot we have the wiki available ^^'