Refining Docstrings for Code API Enhancement

[jakubjezek001]

Description:

In order to enhance our code API, it is essential that we refine the docstrings for every method and class. Additionally, each module category's __init__.py file should contain a clear and concise docstring explaining its purpose. This initiative will be particularly beneficial as we transition to using Sphinx for documentation generation.

Steps to Reproduce:

1. Review and update docstrings for all methods and classes.
2. Ensure that each module category's __init__.py file includes a descriptive docstring.
3. Verify the changes by generating documentation using Sphinx.

Expected Outcome:

Improved code readability and documentation quality, facilitating better understanding and usage of the API.

[jakubjezek001]

here is great example of the docsting style, taken from here https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example:

"""
.. module:: useful_1
   :platform: Unix, Windows
   :synopsis: A useful module indeed.

.. moduleauthor:: Andrew Carter <[email protected]>


"""

def public_fn_with_googley_docstring(name, state=None):
    """This function does something.

    Args:
       name (str):  The name to use.

    Kwargs:
       state (bool): Current state to be in.

    Returns:
       int.  The return code::

          0 -- Success!
          1 -- No good.
          2 -- Try again.

    Raises:
       AttributeError, KeyError

    A really great idea.  A way you might use me is

    >>> print public_fn_with_googley_docstring(name='foo', state=None)
    0

    BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.

    """
    return 0

def public_fn_with_sphinxy_docstring(name, state=None):
    """This function does something.

    :param name: The name to use.
    :type name: str.
    :param state: Current state to be in.
    :type state: bool.
    :returns:  int -- the return code.
    :raises: AttributeError, KeyError

    """
    return 0

def public_fn_without_docstring():
    return True

def _private_fn_with_docstring(foo, bar='baz', foobarbas=None):
    """I have a docstring, but won't be imported if you just use ``:members:``.
    """
    return None


class MyPublicClass(object):
    """We use this as a public class example class.

    You never call this class before calling :func:`public_fn_with_sphinxy_docstring`.

    .. note::

       An example of intersphinx is this: you **cannot** use :mod:`pickle` on this class.

    """

    def __init__(self, foo, bar='baz'):
        """A really simple class.

        Args:
           foo (str): We all know what foo does.

        Kwargs:
           bar (str): Really, same as foo.

        """
        self._foo = foo
        self._bar = bar

    def get_foobar(self, foo, bar=True):
        """This gets the foobar

        This really should have a full function definition, but I am too lazy.

        >>> print get_foobar(10, 20)
        30
        >>> print get_foobar('a', 'b')
        ab

        Isn't that what you want?

        """
        return foo + bar

    def _get_baz(self, baz=None):
        """A private function to get baz.

        This really should have a full function definition, but I am too lazy.

        """
        return baz
        ```

[tweak-wtf]

looking at the example, should we remove the type hints from signatures or rather add more?

[jakubjezek001]

looking at the example, should we remove the type hints from signatures or rather add more?

definitelly rather more please :)

[tweak-wtf]

your wish is my command :D

[tweak-wtf]

i'll start with this when #8 got merged as it brings quite some changes.
i'll probably do that directly on #17 as i already added some vanilla sphinx autodocs