Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #9495

Re: Proposal to extend PEP 257 (New Documentation String Spec)

Show all headers | View raw

rantingrick <rantingrick@gmail.com> writes:

> ---------------------------------------
>  New Syntax Specification For Documentation Strings
> ---------------------------------------
>
> """ {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
> {NEWLINE}
> {LONG_DESCRIPTION_HERE}
> {NEWLINE}
> Arguments: (if applicable)
>     {ARGUMNET_1} <{TYPE}>:
>         ARGUMENT_1_DESCRIPTION}
>     {ARGUMNET_2} <{TYPE}>:
>         ARGUMENT_2 DESCRIPTION}
>     {ARGUMNET_N} <{TYPE}>:
>         ARGUMENT_N_DESCRIPTION}
> {NEWLINE}
> """

I use reStructuredText formatting in my PEP 257 docstrings:

    def frobnicate(spong, mode="wibble"):
        """ Frobnicate the spong.

            :param spong: The SpongDrabble instance to be frobnicated.
            :param mode: Specific frobnication mode to use. Valid modes
                are "wibble", "wobble", "warble".
            :return: The blagule from the frobnication.

            Note that the Weebly-Ruckford algorithm is used for
            frobnication portability. See
            <http://ruckford.example.com/>_ for details.

            """
        pass
        pass
        pass

I would be happy to see these conventions be more formalised; after all,
reStructuredText was originated as a means of formatting documentation
in Python docstrings.

-- 
 \        “All opinions are not equal. Some are a very great deal more |
  `\    robust, sophisticated and well supported in logic and argument |
_o__)                                     than others.” —Douglas Adams |
Ben Finney

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-14 16:02 -0700
  Re: Proposal to extend PEP 257 (New Documentation String Spec) Ben Finney <ben+python@benfinney.id.au> - 2011-07-15 10:24 +1000
  Re: Proposal to extend PEP 257 (New Documentation String Spec) Michael Hrivnak <mhrivnak@hrivnak.org> - 2011-07-15 02:00 -0400
  Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-15 17:13 +1000
    Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-15 11:56 -0700
      Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-16 09:16 +1000
        Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-16 08:32 -0700
          Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-17 02:25 +1000
          Re: Proposal to extend PEP 257 (New Documentation String Spec) Andrew Berg <bahamutzero8825@gmail.com> - 2011-07-16 18:03 -0500
            Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-16 16:25 -0700
              Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-17 09:45 +1000
          Re: Proposal to extend PEP 257 (New Documentation String Spec) Andrew Berg <bahamutzero8825@gmail.com> - 2011-07-16 18:44 -0500
      Re: Proposal to extend PEP 257 (New Documentation String Spec) Michael Hrivnak <mhrivnak@hrivnak.org> - 2011-07-16 15:23 -0400
        Re: Proposal to extend PEP 257 (New Documentation String Spec) Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-07-17 13:10 +1000
          Re: Proposal to extend PEP 257 (New Documentation String Spec) Tim Chase <python.list@tim.thechases.com> - 2011-07-17 06:11 -0500
            Re: Proposal to extend PEP 257 (New Documentation String Spec) rantingrick <rantingrick@gmail.com> - 2011-07-17 10:30 -0700
      Re: Proposal to extend PEP 257 (New Documentation String Spec) Chris Angelico <rosuav@gmail.com> - 2011-07-17 09:09 +1000
  Re: Proposal to extend PEP 257 (New Documentation String Spec) George Rodrigues da Cunha Silva <georger.silva@gmail.com> - 2011-07-15 12:44 -0300

csiph-web