PEAR documentation

Two questions about documentation:

1) I've written a class (DB_Table_Database) with a lot of
private 
properties that are accessed through get* functions. In the
in-code 
documentation, I wrote documentation blocks for each of the
private 
properties, some of which are multi-dimensional arrays. 
These don't 
appear in the API documentation that is generated for the
PEAR web page 
because the properties are marked access private. The get*
functions 
are documented in a minimal fashion (e.g., "Returns the
private property 
array ..., or a part thereof"), but this is not
particularly useful to a 
user without accessible documentation of the contents and
structure of 
the corresponding property.

I could move all of the documentation of each private
property into the 
docblock for its getter function. I could also just
explicitly say:
read the docblocks in the source code. My question is: What
do you all 
consider "best practice" for how to write phpdoc
api documentation for 
private properties that are accessible through a get
function?

2) I'd like to write DocBook documentation for the DB_Table
package, but 
am having trouble with the software required to rebuild the
PEAR manual, 
or a part of it. What is the right place to post questions
about the 
details of this documentation production process?

regards,
David



!-----------------------------------------------------------
--------!	
!  David Morse				email: morsecems.umn.edu   !
!  Dept of Chem Eng & Mat Sci		phone: (612)625-0167	   
!
!  University of Minnesota					    !
!  Minneapolis, MN 55455					    !
!-----------------------------------------------------------
--------!

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

On Fri Mar 09, 2007 at 11:1039AM -0600, David Morse wrote:
> read the docblocks in the source code. My question is:
What do you all 
> consider "best practice" for how to write
phpdoc api documentation for 
> private properties that are accessible through a get
function?

I'd document the property in the documentation block for the
get method.

> 2) I'd like to write DocBook documentation for the
DB_Table package, but 
> am having trouble with the software required to rebuild
the PEAR manual, 
> or a part of it. What is the right place to post
questions about the 
> details of this documentation production process?

pear-doclists.php.net is the right mailing list.  Or feel
free to get
in touch with me off-list.

- Martin

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php