Thread: [Epydoc-devel] How to document properties?
Brought to you by:
edloper
From: Hans M. <me...@in...> - 2007-05-14 08:34:42
|
Hi! On the page I recently posted, I note a problem I currently have - e.g. I want to document my base class for XFig objects: 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)""" 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.radius = -1 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. Can you advise me how to approach this? http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/apidox/fig.Object-class.html As you can read here: http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-documentation 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 |
From: Hans M. <me...@in...> - 2007-05-16 11:08:15
|
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 |
From: Daniele V. <pi...@de...> - 2007-05-16 11:57:17
|
> 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.) You may group such constants using group markers. See http://epydoc.sourceforge.net/epydoc.html#grouping-and-sorting: #{ polygon types ptPolyline = 1 ptBox = 2 ptPolygon = 3 ptArcBox = 4 ptPictureBBox = 5 #{ ellipse types etEllipseRadii = 1 etEllipseDiameter = 2 etCircleRadius = 3 etCircleDiameter = 4 ... There is no such thing as an enum in Python, neither there are constants. Be explicit with how variables are expected to be used: call your groups "polygon types constants", for example. -- Daniele Varrazzo - Develer S.r.l. http://www.develer.com |
From: Hans M. <me...@in...> - 2007-05-16 12:38:00
|
Am Mittwoch, 16. Mai 2007 13:57:11 schrieb Daniele Varrazzo: > >> As you can read here: > >> http://kogs-www.informatik.uni-hamburg.de/~meine/software/figpy/#api-doc > >>ume 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.) > > You may group such constants using group markers. See > http://epydoc.sourceforge.net/epydoc.html#grouping-and-sorting: > > #{ polygon types > ptPolyline = 1 > ptBox = 2 > ptPolygon = 3 > ptArcBox = 4 > ptPictureBBox = 5 What a pity that I cannot cross-reference the functions these "constants" are to be used in in the #{ caption: #{ polygon types constants (cf. `PolylineBase.changeType`) does not work (reST mode). :-( -- Ciao, / / /--/ / / ANS |
From: Hans M. <me...@in...> - 2007-05-16 12:11:25
|
Am Mittwoch, 16. Mai 2007 13:57:11 schrieb Daniele Varrazzo: > You may group such constants using group markers. See > http://epydoc.sourceforge.net/epydoc.html#grouping-and-sorting: > > #{ polygon types > ptPolyline = 1 > ptBox = 2 > ptPolygon = 3 > ptArcBox = 4 > ptPictureBBox = 5 Thanks a lot, Daniele! BTW: The link helped me a lot, too! Believe it or not, but I did not yet find http://epydoc.sourceforge.net/epydoc.html, since I was reading "Epydoc Manual" as a caption in the style of "Related Information", and I was only looking at the "smaller" http://epydoc.sourceforge.net/manual-###.html links below. ;-/ > There is no such thing as an enum in Python, neither there are constants. > Be explicit with how variables are expected to be used: call your groups > "polygon types constants", for example. Good idea, thanks. -- Ciao, / / /--/ / / ANS |
From: Daniele V. <pi...@de...> - 2007-05-16 12:23:52
|
> BTW: The link helped me a lot, too! Believe it or not, but I did not yet > find > http://epydoc.sourceforge.net/epydoc.html, since I was reading "Epydoc > Manual" as a caption in the style of "Related Information", and I was only > looking at the "smaller" http://epydoc.sourceforge.net/manual-###.html links > below. ;-/ Thank you for the feedback: we may update the homepage as: <a>Epydoc manual (single page)</a> One chapter per page: * <a>Installing Epydoc</a> * <a>Using Epydoc</a> * ... -- Daniele Varrazzo - Develer S.r.l. http://www.develer.com |