[Xapian-devel] ruby bindings documentation

[Olly Betts]

On Tue, Dec 11, 2007 at 10:49:46AM -0600, Daniel Brumbaugh Keeney wrote:
> I am interested in helping with the documentation for the Ruby
> bindings of Xapian.

Great!

> Very little is documentation is currently
> available in RDoc, Ruby's standard documentation system. I'm not
> familiar with Xapian, I would like to do this in part so I can learn
> the API. I'm also not familiar with C++, however, I believe with the
> examples I can figure out how the C++ documentation applies to Ruby.
> Basically:
> 
> Is anyone working on this?

Not that I'm aware of.

> Is there more Ruby-specific documentation beyond what is found (and
> linked to) on <http://www.xapian.org/docs/bindings/ruby/>?

That's it currently.

> Who do I ask if I can't understand the C++ documentation?

Ask here, or #xapian on freenode.

> Where can I find the source of the current RDoc?

It's generated from ruby/xapian.rb in xapian-bindings:

http://svn.xapian.org/trunk/xapian-bindings/ruby/xapian.rb?view=co

I only added the make rules to produce the RDocs yesterday, so you'll
need to look at SVN HEAD to see them.  For information about working
with an SVN checkout, see:

http://svn.xapian.org/trunk/xapian-core/HACKING?view=co

I'd suggest studying how we do this for Python.  Essentially, the C++
headers have documentation comments which we collate into the C++ API
documentation using doxygen (http://www.doxygen.org/).  Doxygen can
also output XML, so we do this, and then parse it using a script to
generate Python docstrings:

http://svn.xapian.org/trunk/xapian-bindings/python/doxy2swig.py.in?view=co

In some cases, the C++ doxygen comment needs adjusting or replacing,
so it's possible to specify overrides:

http://svn.xapian.org/trunk/xapian-bindings/python/extracomments.i?view=markup

But if you find C++ doxygen comments which are incomplete, incorrect, or
could be tweaked to read well for both C++ and Ruby, let us know rather
than just overriding them.  It's better to fix the master version instead.

Richard Boulton actually put together this stuff for Python, so he's
probably better able to answer questions on the details.  He reads this
list and is also often on IRC.

Ultimately it would be great to be able to do this for all the languages
we support, so if anyone knows the ins and outs of the documentation
system for one of the other supported languages and would like to work
on this, that'd be cool too.

Cheers,
    Olly