Double-check the preferred docstring format

Python docstrings can be formatted in different styles. The most common ones are shown below.

The current code base does not have a uniform style and it is therefore a good opportunity now to choose a style and start using that style throughout the code base.

I am personally leaning towards the NumPy/SciPy style as it appears to be well documented, is used by the scientific community and invites to a documentation style that appears to me better suited for a research/scientific context. That being said, this is a subjective stance and the Google style is very similar although it appears to me to have less documentation. I feel that the documentation provided by NumPy would be of great value to the students, researchers, and contributors who may be unsure on how to go about to format their comments and docstrings.

The Sphinx docs - Google vs NumPy mention:

NumPy style tends to require more vertical space, whereas Google style tends to use more horizontal space. Google style tends to be easier to read for short and simple docstrings, whereas NumPy style tends be easier to read for long and in-depth docstrings.

Note to @amiller: You may wonder whether we had already chosen a style ... we actually had done so last year and but it was never implemented as the very quick decision happened right before I left the project.

Most Common Docstring Formats

Formatting Type	Description	Supported by Sphynx	Formal Specification
reStructuredText	Official Python documentation standard; Not beginner friendly but feature rich	Yes	Yes
NumPy/SciPy docstrings	NumPy’s combination of reStructured and Google Docstrings	Yes	Yes
Google docstrings	Google’s recommended form of documentation	Yes	No

source: Real Python: Documenting Python Code: A Complete Guide

Resources

https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

reStructuredText example

async def mimc_mpc(context, x, k):
    """MiMC block cipher encryption encrypts message :math:`x` with
    secret key :math:`k`, where either :math:`x` or :math:`k` can be
    secret share, the other is an element of :math:`F_p`.

    See: https://eprint.iacr.org/2016/542.pdf

    :arg honeybadgermpc.mpc.Mpc context: The MPC context object
    :arg honeybadgermpc.progs.mixins.dataflow.Share x: The secret share to encrypt
    :arg honeybadgermpc.field.GFElement k: The secret key used to encrypt
    :returns: the encrypted share
    :rtype: honeybadgermpc.progs.mixins.dataflow.Share
    """

NumPy/SciPy Docstrings example

async def mimc_mpc(context, x, k):
    """MiMC block cipher encryption encrypts message :math:`x` with
    secret key :math:`k`, where either :math:`x` or :math:`k` can be
    secret share, the other is an element of :math:`F_p`.

    See: https://eprint.iacr.org/2016/542.pdf

    Parameters
    ----------
    context : honeybadgermpc.mpc.Mpc
        The MPC context object.
    x : honeybadgermpc.progs.mixins.dataflow.Share
        The secret share to encrypt.
    k : honeybadgermpc.field.GFElement
        The secret key used to encrypt.

    Returns
    -------
    honeybadgermpc.progs.mixins.dataflow.Share
        The encrypted share.
    """

Google Docstrings example

async def mimc_mpc(context, x, k):
    """MiMC block cipher encryption encrypts message :math:`x` with
    secret key :math:`k`, where either :math:`x` or :math:`k` can be
    secret share, the other is an element of :math:`F_p`.

    See: https://eprint.iacr.org/2016/542.pdf

    Args:
        context (honeybadgermpc.mpc.Mpc): The MPC context object.
        x (honeybadgermpc.progs.mixins.dataflow.Share): The secret share to encrypt.
        k (honeybadgermpc.field.GFElement): The secret key used to encrypt.

    Returns:
        honeybadgermpc.progs.mixins.dataflow.Share: The encrypted share.
    """

initc3 / HoneyBadgerMPC