Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Establish consistent docstring style, and use docformatter #56

Closed
willdumm opened this issue Sep 12, 2024 · 1 comment
Closed

Establish consistent docstring style, and use docformatter #56

willdumm opened this issue Sep 12, 2024 · 1 comment
Assignees

Comments

@willdumm
Copy link
Contributor

willdumm commented Sep 12, 2024

Looks like we need a consistent docstring format. Even just in molevol.py there are quite a few variations. I'll suggest the following for detailed doc strings (mostly inspired by the linked comment):

"""
Short one-line description of function or method.

Additional general detail if desired

Args:
    argument1 (type): Description
    argument2 (type): Long description may take up
        multiple lines, with a single additional indent level (four spaces) denoting subsequent lines after the first

Returns:
    return_type: Description, with indenting rules from above.
"""

A few other suggested details (following how e.g. gctree formats doc strings)

  • Class doc strings may have an additional Attributes: header describing public attributes. Constructor documentation, including Args: should be provided in the class-level docstring.
  • Additional headers like Notes: and Examples: can appear after Returns:.

Questions:

  • If we're going to use Sphinx autodoc like gctree does, we should consider omitting the (type) annotations on arguments and return values, because autodoc gets those from type annotations, and automatically links them to the relevant documentation for that type.
  • Also a sphinx thing, inline code requires double back quotes like
    ``inline code``.
    However, any inline mention of a method, function, or class should be formatted like:
    :meth:`name`, :func:`name`, or :class:`name`
    so that autodoc will insert the link to the corresponding documentation. Do we want to use these here?
  • In gctree, all public functions are required to have a docstring, and private functions (e.g. beginning with underscore) have a docstring only when it seems helpful. Keep that policy here?

Inspired by the comment from @matsen in #50 (comment)

@matsen
Copy link
Contributor

matsen commented Sep 27, 2024

Closed by #59

@matsen matsen closed this as completed Sep 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants