Mailing-List: contact dev-help@lucy.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@lucy.apache.org
To: dev@lucy.apache.org
References: <git-pr-18-lucy@git.apache.org>
 <CAAS6=7iOgNcTfCty6EtVhKYaMjDWx2JXTB3wePkhBeyOOERfxQ@mail.gmail.com>
From: Nick Wellnhofer <wellnhofer@aevum.de>
Message-ID: <55F064FC.5070309@aevum.de>
Date: Wed, 9 Sep 2015 18:57:32 +0200
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101
 Thunderbird/38.2.0
MIME-Version: 1.0
In-Reply-To: 
 <CAAS6=7iOgNcTfCty6EtVhKYaMjDWx2JXTB3wePkhBeyOOERfxQ@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [lucy-dev] [GitHub] lucy pull request: Generate Perl POD from
 public methods

On 09/09/2015 03:30, Marvin Humphrey wrote:
> I reviewed a diff of the generated POD before and after merging this branch
> (and the corresponding Clownfish branch). A summary of the changes is below my
> sig.
>
> Unsurprisingly for a change of this magnitude, there were a few glitches.
> These are the ones I think we should to attend to:
>
> *   Restore Doc#add_fields.
> *   IndexReader#offsets became IndexReader#_offsets and should be restored.

These two are glitches.

> *   Restore documentation for several methods IndexSearcher inherits
>      from Searcher.  Same with PolySearcher (though it's a less important
>      class).
> *   The PostingList methods Next, Advance, and Get_Doc_ID should become
>      public.
> *   Restore BitCollector#collect
> *   Restore ANDQuery#add_child and ORQuery#add_child.

These are all methods that *are* documented in a parent class. We should 
automatically document them in a subclass if they're the first implementation 
of an abstract method.

This leaves:

- IndexSearcher#hits, IndexSearcher#get_schema, documented in
   Lucy::Search::Searcher
   https://metacpan.org/pod/Lucy::Search::Searcher
- PostingList#advance, documented in Lucy::Search:Matcher
   https://metacpan.org/pod/Lucy::Search::Matcher
- ANDQuery#add_child, ORQuery#add_child, documented in
   Lucy::Search::PolyQuery (not in 0.4 but in master)

We could document these methods a second time in a subclass but it would be 
somewhat inconsistent.

Nick