[Rubygems-developers] RubyGems API Docs

[Mauricio Fernández]

On Tue, Dec 07, 2004 at 07:11:09AM -0500, Jim Weirich wrote:
> On Tuesday 07 December 2004 04:37 am, Mauricio Fernández wrote:
> > On Fri, Dec 03, 2004 at 10:58:08AM -0500, Richard Kilmer wrote:
> > > The whole API is public in that it is open source.  All the classes can
> > > be manipulated by any person that wants (on their own machine, etc), and
> > > we
> >
> > There is a distinction between API and mere source code, though.
> 
> No, you are right, there is a distinct difference.  When I used the term, I 
> was differentiating between design documentation and documentation about how 
> to call and use the existing objects in the system.  In other words, the 
> object level interfaces, as opposed to the system level API.  Perhaps it 
> would be better to just call it the "rdocs" (just as java programmers refer 
> to their "javadocs"), thereby leaving the confussing "A" out of the PI. 
> 
> That's all I meant by it.

I see. Would it make sense to work on the interface and come up with
something that can rightfully be called *A*PI? 

I think this would be good because:
* since RubyGems is meant to become the Ruby standard, you'll want to
  ensure backwards compatibility, as Rich pointed out. This is much
  easier if you explicitly expose some parts of RubyGems through a
  public API.
* it is in RubyGems' best interest to make people view it not only as a
  tool but also as a codebase to build upon through well-defined
  interfaces. This opens the door to more intelligent tools that
  leverage RubyGems' infrastructure.
* the creation of such tools would be easier if you offer a stable
  target
* it is better to do it now before code dependent on RubyGems can be
  broken by the ongoing refactoring.
* the creation of an API can happen in parallel with the current
  refactoring (re: RemoteInstaller) and makes the code arguably cleaner
  and easier to document.

What do you think?

-- 
Hassle-free packages for Ruby?
RPA is available from http://www.rubyarchive.org/