Situation

Currently, the situation with docstrings in classes and functions seems to me ambiguous and inconsistent. 😉 Some are pretty well documented, others are not.
Additionally, some signatures contain conflicting information between docstrings and type annotations, for example:

# file ics/icalendar.py
class Calendar(Component):
    # [...]
    def __init__(
        self,
        imports: Union[str, Container] = None,
        events: Iterable[Event] = None,
        todos: Iterable[Todo] = None,
        creator: str = None
    ):
        """Instantiates a new Calendar.

        Args:
            imports (**str**): data to be imported into the Calendar,
            events (**Set[Event]**): Events to be added to the calendar
            todos (Set[Todo]): Todos to be added to the calendar
            creator (string): uid of the creator program.

        If ``imports`` is specified, every other argument will be ignored.
        """

Compare the arguments imports, events, and todos in the docstring and with the type annotation. Both are advertised differently. This is one of the worst situations when documenting stuff: conflicting information. IMHO this should be improved to avoid confusing our developers.

Questions

1. Why are types both included into docstring and type annotations? This seems to be double work. Shouldn't there be only one location?
2. Shouldn't the types automatically inserted when building the documentation using the sphinx-autodoc-typehints plugin?
3. Shouldn't have every file a global docstring about its purpose, license, probably dependencies, author(s) etc.?
4. Why are some classes included in the API documentation and others are not? For example, the class Organizer in file organizer.py, Timeline in timeline.py and others.

Proposed Solution

1. Create a consistent docstring "spec" to improve consistency for every function. For example, a docstring should contain (at least):

   • the purpose of the function/class member/etc.
   • a description of its arguments
   • the return value, if applicable
   • does the function raises exceptions?
   • any dependencies? Restrictions?
   • In some cases, examples could help.

2. We should check if we could rephrase docstring which contains the pipe symbol (|); it should be avoided due to consistency reasons (interactive Python shell).

3. Document the missing pieces to improve API documentation.

4. Avoid ambiguous types between docstring and type annotation. Ideally, type annotations are included into the API documentation without explicitly mention it in the docstring.