[as2api-dev] private

[David Holroyd]

On Fri, Sep 09, 2005 at 02:34:30PM +0200, Michael Nisi wrote:
> Hi David,
> 
> I agree 100%. Documentation for an API should never include private members.
> 
> The reason for my request is quite more practible. If you work in a team, 
> it's nice to use documentation as development tool. New team members can 
> browse the docs, discuss code, etc. Without a feature like that we have to 
> browse source and read comments there. 
> 
> The point is, I sometimes need to be able to document for the person who 
> writes the API, not the one who uses it. 

To which the counterpoint (from the devil's advocate point of view) is
that the person trying to understand the API's implementation (of which
private methods are a part) needs to read the source anyway.


> ps. give me a hint and I'll edit my version -- I'll find it anyways ;)

Sure.  If you check out the latest code from Subversion, e.g.,

  svn checkout http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api

and look in the file 'output/html/html_framework.rb',

  http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/output/html/html_framework.rb

you'll find a utility method in the class 'Page' called
document_member?(),

  def document_member?(member)
    !member.access.private?
  end

I think you'll get the effect you're after if you change that to,

  def document_member?(member)
    true
  end


hope that helps,
dave

-- 
http://david.holroyd.me.uk/