Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Documenting properties

Reply
Thread Tools

Documenting properties

 
 
=?ISO-8859-1?Q?Lasse_V=E5gs=E6ther_Karlsen?=
Guest
Posts: n/a
 
      09-27-2005
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/
(E-Mail Removed)
PGP KeyID: 0x2A42A1C2
 
Reply With Quote
 
 
 
 
Paul McNett
Guest
Posts: n/a
 
      09-27-2005
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


 
Reply With Quote
 
 
 
 
Gerrit Holl
Guest
Posts: n/a
 
      09-27-2005
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.
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Documenting VisionSet Java 10 02-01-2006 09:10 PM
documenting projects Nikhil Patel ASP .Net 1 10-11-2004 05:03 PM
ANN: zOxygen Documenting Utility Jussi Jumppanen Java 0 04-21-2004 05:46 AM
Documenting properties created by property() properly Brian Dam Pedersen Python 1 07-29-2003 11:58 AM
Documenting ASP.NET Tim Almond ASP .Net 1 07-12-2003 03:21 PM



Advertisments