Enhance docstrings and add examples

[namsaraeva]

We should check all docstring so that they match in the format. Add examples where needed.

[namsaraeva]

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.
    Args:
        param1: The first parameter.
        param2: The second parameter.
    Returns:
        The return value. True for success, False otherwise.
    """

I prefer this format over our current. What do you think @sophiamaedler?

[Zethson]

@namsaraeva is suggesting Google docstring format instead of numpy.
I can happily switch to whatever when switching to the scverse template.

[sophiamaedler]

I'm fine with either. What's the preferred standard in scverse packages at the moment?

Would be good if we could implement some sort of check when adding new commits after switching to make sure that all doc strings are in the chosen format. We had some mismatched formats in the past that I went through and homogenized.

[Zethson]

It's numpy by default but many use Google (e.g. me). It's more or less a 50/50 split.

Would be good if we could implement some sort of check when adding new commits after switching to make sure that all doc strings are in the chosen format. We had some mismatched formats in the past that I went through and homogenized.

No worries, I got you :)

[sophiamaedler]

Then let's go with Google :-)

Let me know if you need help with something.

[sophiamaedler]

this should be addressed as part of #43