solrb documentation (was Re: SV: Re: SOLR-116)

[Erik Hatcher <er...@ehatchersolutions.com>]

On Feb 1, 2007, at 6:47 AM, Zaheed Haque wrote:
> I think trying to tackle two problem (Learning Solr as well as
> solrb/flare) at the
> same time is giving the problem. While I was writing the i18n unit  
> test I found
> out the 100% test cov. thats really cool. Now in terms of docs.. I
> think it would
> be great if I have a
>
> - TODO file under client/ruby/solrb. What I mean is that - lot of  
> times
> I find information in wiki which applies to Solr but I don't know  
> if it applies
> to solr-ruby-api. So it would be nice to have a TODO file (Things  
> that is
> not available in solr-ruby yet. Makes my life easier.

We have our own solrb TODO list on the wiki: <http://wiki.apache.org/ 
solr/solrb/ToDo>, also note the "rake todo" task that will produce a  
list of all the TBD/TODO/FIXME lines in the code.

> - I am completely lost in terms of facets.. I would love to have  
> some more info
> about it. I couldn't follow the facet's part of the code when i was
> looking at the test/unit/standard_request.rb and standard_response.rb,
> It would be nice if
> there were some explanation regarding facets in the .rb files.

Quite fair enough.

However, rather than reinvent the wheel, have you read these?

  - <http://wiki.apache.org/solr/SolrFacetingOverview>
  - <http://wiki.apache.org/solr/SimpleFacetParameters>

Granted the difference is that through solrb we map more readable  
names to the arguments, along a sensible data-structure of parameters:

     request = Solr::Request::Standard.new(:query => 'query',
        :facets => {
          :fields => [:genre,
                      # field that overrides the global facet parameters
                      {:year =>
                         {:limit => 50, :mincount => 0, :missing =>  
false, :sort => :term, :prefix=>"199"}}],
          :queries => ["q1", "q2"],
          :prefix => "cat",
          :limit => 5, :zeros => true, :mincount => 20, :sort  
=> :count  # global facet parameters
         }
     )

I have to stop and laugh when I see this versus the vastly more  
succinct query string this generates, and wonder if the syntactic  
sugar is really worth it :)  One nicety is that nested values like a  
field-specific override of the mincount is easier to visually parse  
with the Ruby code.

So while I'm in complete agreement with you that solrb's rdocs need  
lots of improvements, I also don't want the docs to be a copy of what  
Solr docs already explain nicely.

> If you prefer, what I could do is comment the code as I see it based
> on the functional
> test and then you can edit it this way we could beef up the doc rather
> quick. Its not that
> many files so I could give it a shot by end day tomorrow. Off course
> except Facets :-)

Sure thing!  Patches are always welcome, and even more welcome when  
they are documentation patches :)

	Erik