convention for documenting function parameters in doc strings

Discussion in 'Python' started by danielx, Feb 8, 2010.

  1. danielx

    danielx Guest

    Is there a convention for how to document function (or method)
    parameters in doc strings? Recently, I've been doing alot of PHP
    programming, and in PHPdoc, you'd do it like this:

    /*
    * @param type $foo Description.
    *
    * @return type Description.
    */
    function bar($foo) {
    ...
    }

    Is there an equivalent convention I (c|sh)ould be using in my Python
    docstrings? I saw that Python 3 has function annotations, which could
    be used for this purpose, but function annotations have no particular
    purpose within the language itself (which seems like a mistake to me),
    and they don't exist in the Python 2.x series (at least not the older
    versions).
    danielx, Feb 8, 2010
    #1
    1. Advertising

  2. danielx wrote:
    > Is there a convention for how to document function (or method)
    > parameters in doc strings? Recently, I've been doing alot of PHP
    > programming, and in PHPdoc, you'd do it like this:
    >
    > /*
    > * @param type $foo Description.
    > *
    > * @return type Description.
    > */
    > function bar($foo) {
    > ...
    > }
    >
    > Is there an equivalent convention I (c|sh)ould be using in my Python
    > docstrings? I saw that Python 3 has function annotations, which could
    > be used for this purpose, but function annotations have no particular
    > purpose within the language itself (which seems like a mistake to me),
    > and they don't exist in the Python 2.x series (at least not the older
    > versions).
    >

    Different strategies here:

    1/ most doc builders propose their own format. You can stick to it if
    you don't want to use another builder (e.g. epydoc has a specific syntax
    to document signatures)
    2/ Use a 'standard' format, usually these formats are a bit more formal
    but they gain in portability, most builders support these formats.
    reStructuredText is one of them and supported by all python doc builders.

    http://epydoc.sourceforge.net/manual-othermarkup.html

    JM
    Jean-Michel Pichavant, Feb 8, 2010
    #2
    1. Advertising

  3. danielx

    danielx Guest

    On Feb 8, 2:49 am, Jean-Michel Pichavant <>
    wrote:
    > danielx wrote:
    > > Is there aconventionfor how to document function (or method)
    > > parameters in doc strings? Recently, I've been doing alot of PHP
    > > programming, and in PHPdoc, you'd do it like this:

    >
    > > /*
    > >  * @param type $foo Description.
    > >  *
    > >  * @return type Description.
    > >  */
    > > function bar($foo) {
    > >   ...
    > > }

    >
    > > Is there an equivalentconventionI (c|sh)ould be using in my Python
    > > docstrings? I saw that Python 3 has function annotations, which could
    > > be used for this purpose, but function annotations have no particular
    > > purpose within the language itself (which seems like a mistake to me),
    > > and they don't exist in the Python 2.x series (at least not the older
    > > versions).

    >
    > Different strategies here:
    >
    > 1/ most doc builders propose their own format. You can stick to it if
    > you don't want to use another builder (e.g. epydoc has a specific syntax
    > to document signatures)
    > 2/ Use a 'standard' format, usually these formats are a bit more formal
    > but they gain in portability, most builders support these formats.
    > reStructuredText is one of them and supported by all python doc builders.
    >
    > http://epydoc.sourceforge.net/manual-othermarkup.html
    >
    > JM


    Thanks for the link, Jean-Michel. I was hoping to find out more about
    how this is don in reStructuredText, since that seems to be what's
    used to document Python at docs.python.org. There is a section in the
    page that you linked to which describes how documenting function
    parameters in reST works, which seems to be what I was looking for.
    danielx, Feb 10, 2010
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Matt
    Replies:
    3
    Views:
    484
    Tor Iver Wilhelmsen
    Sep 17, 2004
  2. Thomas Sommer
    Replies:
    0
    Views:
    423
    Thomas Sommer
    Nov 25, 2004
  3. Mike
    Replies:
    3
    Views:
    2,244
    Victor Bazarov
    Oct 28, 2004
  4. Ben

    Strings, Strings and Damned Strings

    Ben, Jun 22, 2006, in forum: C Programming
    Replies:
    14
    Views:
    739
    Malcolm
    Jun 24, 2006
  5. Replies:
    11
    Views:
    191
    Jürgen Exner
    Aug 25, 2008
Loading...

Share This Page