Documenting parameters

See also

I’m wondering if people have suggestions on the best way to format function/method docstrings so it’s possible to get Sphinx’s fancy formatting and yet retain nice and readable docstrings from the Python prompt. I’m especially interested in how to document the function/ method input “parameters”.

I know about the :param name: stanza but when there’s a relatively long list of parameters, I don’t find it very readable from the Python prompt. Of course, once processed by Sphinx, it yields great looking documentation.

I also know about http://packages.python.org/an_example_pypi_project/sphinx.html and the googley and sphinxey variants. I’m thinking there must be a good compromise here.

For return values, I often use the following in my docstrings:

returns:
out1:something
out2:something else

Indentation and proper alignment make this easy to read and it looks great once processed by Sphinx. But I can’t find a similar syntax for parameters and keywords. I thought (and obviously I’m wrong) that Sphinx accepted :parameters: and :keywords: but those don’t look nice once processed, e.g., to html. In particular, :parameters: is converted to “Parameters :” (with a space), which often causes the colon to end on a new line below the word “Parameters”.

It would be great to be able to write:

parameters:
in1:description of in1
in2:description of in2
keywords:
kw1:description of kw1

just the same way we can use :returns:. I’m happy to try and add this if it sounds like a good idea. I’d like to hear what people think anyways.

Thanks.

Example documenting parameters

Constants

COMMAND_SUCCESS

The CR_S_SUCCESS value is returned when a command is successfull.

Value Name French Message
0x00000000L COMMAND_SUCCESS Opération réussie.

List of error codes

Value Name French Message
0x8130F001L CR_E_FAILED Une vérification de cohérence interne a échoué.
0x8130F002L CR_E_TIMEOUT Le délai a expiré.
0x8130F003L CR_E_SEND_DATA_FAILED L’envoi des données a échoué.
0x8130F004L CR_E_OPEN_PORT_FAILED L’ouverture du port COM a échoué.
0x8130F005L CR_E_CLOSE_PORT_FAILED La fermeture du port COM a échoué.
0x8130F006L CR_E_BAD_SYNCHRO Erreur de synchronisation avec la base.
0x8130F007L CR_E_BAD_ADDRESS Mauvaise adresse.
0x8130F008L CR_E_BAD_SIZE Taille incorrecte.
0x8130F009L CR_E_BAD_CHANNEL Mauvais canal.
0x8130F00AL CR_E_BAD_STATUS Mauvais statut retourné par la base.
0x8130F00BL CR_E_OPEN_FILE_FAILED Ouverture du fichier a échoué. 
.. c:function:: DWORD CR_RFID_VerifierPIN(ST_CODE_PIN *pCodePIN)

    Le code PIN permet d'autoriser l'utilisation des clés de chiffrement et de
    signature dans le lecteur RFID.

    :Paramètres:
        :entree:
            :pCodePIN: le code PIN à présenter au lecteur RFID.

    :Returns:
       :error:  :ref:`see the error codes <list_error_codes>`
       :success:  :ref:`COMMAND_SUCCESS <cr_success>`

CR_RFID_VerifierPIN

DWORD CR_RFID_VerifierPIN(ST_CODE_PIN *pCodePIN)

Le code PIN permet d’autoriser l’utilisation des clés de chiffrement et de signature dans le lecteur RFID.

Paramètres:
entree:
pCodePIN:le code PIN à présenter au lecteur RFID.
Returns:
error:see the error codes
success:COMMAND_SUCCESS