Documenting properties

Discussion in 'Python' started by =?ISO-8859-1?Q?Lasse_V=E5gs=E6ther_Karlsen?=, Sep 27, 2005.

  1. I notice that if I use this syntax:

    def classname:
    ...
    ##
    # closes the database connection and releases the resources.
    def close(self):
    ....

    ##
    # Returns a list of fields
    fields = property(....)

    then doing:

    help (classname)

    then the text is listed for the property and the method, whereas if I do
    this:

    classname.close.__doc__

    then nothing is listed, and to get that I have to use the """.."""
    syntax to document:

    def close(self):
    """closes the datab..."""
    ....

    then classname.close.__doc__ shows the text.

    So, my question is, is there a way to get __doc__ support for
    properties, in effect, use the """xxx""" syntax for documenting properties.

    Is the preferred way to use """xxx""" or # to document ?
    Whatever is preferred, what's the upside/downsides of the two beyond
    what I just explained?

    --
    Lasse Vågsæther Karlsen
    http://usinglvkblog.blogspot.com/
    mailto:
    PGP KeyID: 0x2A42A1C2
     
    =?ISO-8859-1?Q?Lasse_V=E5gs=E6ther_Karlsen?=, Sep 27, 2005
    #1
    1. Advertising

  2. =?ISO-8859-1?Q?Lasse_V=E5gs=E6ther_Karlsen?=

    Paul McNett Guest

    Lasse Vågsæther Karlsen wrote:
    > So, my question is, is there a way to get __doc__ support for
    > properties, in effect, use the """xxx""" syntax for documenting properties.


    Yes, the property() function accepts a doc argument, as in:

    property(fget, fset, fdel, doc)

    ex:
    MyProp = property(_get, _set, None, "This will show up in __doc__")


    > Is the preferred way to use """xxx""" or # to document ?


    # is for source code commenting (audience is the person reading your
    code). """x""" is for documenting your API (audience is the person using
    your code). They are quite different.


    > Whatever is preferred, what's the upside/downsides of the two beyond
    > what I just explained?


    Nothing really, but something handy to keep in mind is that the string
    literal ("""x""") can be used to block out huge sections of code during
    testing, where you'd have to put a # in front of every line otherwise.

    --
    Paul McNett
    http://paulmcnett.com
    http://dabodev.com
     
    Paul McNett, Sep 27, 2005
    #2
    1. Advertising

  3. =?ISO-8859-1?Q?Lasse_V=E5gs=E6ther_Karlsen?=

    Gerrit Holl Guest

    Paul McNett wrote:
    > > Whatever is preferred, what's the upside/downsides of the two beyond
    > > what I just explained?

    >
    > Nothing really, but something handy to keep in mind is that the string
    > literal ("""x""") can be used to block out huge sections of code during
    > testing, where you'd have to put a # in front of every line otherwise.


    Except, of course, code that contains string literals with triple
    quotes. And with a good editor, it's not too difficult to insert a # in
    front of hundreds of lines :)%s/^/#/g).

    Gerrit.

    --
    Temperature in Luleå, Norrbotten, Sweden:
    | Current temperature 05-09-27 20:19:54 9.8 degrees Celsius ( 49.7F) |
    --
    Det finns inte dåligt väder, bara dåliga kläder.
     
    Gerrit Holl, Sep 27, 2005
    #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. Tim Almond

    Documenting ASP.NET

    Tim Almond, Jul 11, 2003, in forum: ASP .Net
    Replies:
    1
    Views:
    470
    Kevin Spencer
    Jul 12, 2003
  2. Nikhil Patel

    documenting projects

    Nikhil Patel, Oct 11, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    294
    Rakesh Rajan
    Oct 11, 2004
  3. Jussi Jumppanen

    ANN: zOxygen Documenting Utility

    Jussi Jumppanen, Apr 21, 2004, in forum: Java
    Replies:
    0
    Views:
    327
    Jussi Jumppanen
    Apr 21, 2004
  4. VisionSet

    Documenting

    VisionSet, Jan 31, 2006, in forum: Java
    Replies:
    10
    Views:
    751
    Andrew McDonagh
    Feb 1, 2006
  5. Brian Dam Pedersen
    Replies:
    1
    Views:
    342
    Michael Hudson
    Jul 29, 2003
Loading...

Share This Page