Re: [Epydoc-devel] How to document properties?

[Hans M. <me...@in...>]

Hi!

I found a good partial solution that I wanted to try out anyways:

Am Montag, 14. Mai 2007 10:34:32 schrieb Hans Meine:
> class Object(object):
> 	"""Base class of all fig objects.  Handles common properties like
>
> 	- lineStyle (see `lineStyleXXX` constants)
> 	- lineWidth (1/80th inch)
> 	- styleValue (dash length / dot gap ratio), in 1/80th inches
> 	- penColor, fillColor (see `colorXXX` constants)
> 	- fillStyle (see `fillStyleXXX` constants)
> 	- depth (0-999)
> 	- joinStyle (see `joinStyleXXX` constants)
> 	- capStyle (see `capStyleXXX` constants)
> 	- forwardArrow/backwardArrow (`Arrow` objects)"""

	__slots__ = 
["lineWidth", "penColor", "fillColor", "depth", "penStyle", "fillStyle",
				 "styleValue", "joinStyle", "capStyle", "forwardArrow", "backwardArrow"]

> 	def __init__(self):
> 		self.lineStyle = lineStyleDefault
> 		self.lineWidth = 1
> 		self.penColor = colorDefault
> 		self.fillColor = colorDefault
> 		self.depth = 50
> 		self.penStyle = 0 # not used
> 		self.fillStyle = fillStyleNone
> 		self.styleValue = 3.0
> 		self.joinStyle = 0
> 		self.capStyle = 0
> 		self.forwardArrow = None
> 		self.backwardArrow = None
>
> As you can see (yes, this is the complete API), the user is supposed to
> directly access these properties of XFig objects.  However, I would like to
> have them listed in the API documentation in the "properties" section.

This is accomplished with the __slots__ definition, which creates descriptor 
properties (http://docs.python.org/ref/descriptors.html#descriptors).

It also makes the API a little bit more pythonic and more clean, since in my 
case it is a good thing that setting other attributes becomes forbidden.

However, I am now looking for a convenient way of adding docstrings to the 
automatically generated properties.

The "enum problem" mentioned below is a different topic and still unsolved:
> As you can read here:
> http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-docume
>ntation I don't like the large list of "variables" either, which are in fact
> constants and some kind of enum. (Please tell me a better Python API for
> such constants if you know one.)

-- 
Ciao, /  /
     /--/
    /  / ANS