You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucy.apache.org by nwellnhof <gi...@git.apache.org> on 2015/08/27 13:05:51 UTC
[lucy-dev] [GitHub] lucy pull request: Generate Perl POD from public methods
GitHub user nwellnhof opened a pull request:
https://github.com/apache/lucy/pull/18
Generate Perl POD from public methods
The Clownfish branch `perl_pod` adds POD for public novel methods by default, making it possible to remove the POD "whitelists".
This branch also adds Perl documentation for Analyzer, Inversion, and Token, which is needed to write custom analyzers. It also removes documentation for some methods taking private classes as parameters.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/nwellnhof/lucy perl_pod
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/lucy/pull/18.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #18
----
commit e4ecf75b1808c7d87fd738c21ac33d12fffa93d1
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T19:08:11Z
Make Serialize/Deserialize methods private
commit ebe182155189ef4e7a6cbc4010d0b6c2281d9065
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T18:51:14Z
Remove Analysis POD whitelist
All public Analyzer methods are now documented in the Perl API:
- Transform
- TransformText
- Split
- Load
- Dump
commit c198e10f3e492d18b2ba5ae2e312095f81119d6e
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T18:57:25Z
Remove Highlighter POD whitelist
commit 753300094f6a70c998318712d61608477fad0156
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T19:49:13Z
Remove Document POD whitelist
Additional Document methods added to the Perl API:
- Store
- Get_Size
- Extract
- Field_Names
These methods are needed for the C bindings but they aren't really
useful from Perl. They can be blacklisted later.
commit 21252a9dbe50f0df5ea4c1cc95a88516b3a28df6
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T20:31:03Z
Remove Index POD whitelist
Methods that weren't documented in the Perl bindings are made private.
commit 8323f974e3811c44facfd5fed4756ed63b9631dd
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T20:34:58Z
Remove Object POD whitelist
Methods that weren't documented in the Perl bindings are made private.
commit 9a3a96c12b6626483e8e090920763799421b2829
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-20T20:55:52Z
Remove Plan POD whitelist
Document FieldType setters in Perl bindings. Other Methods that weren't
documented are made private.
commit 345fa59440213c049528efdfc1910d80d4dfd8a3
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T11:04:19Z
Remove Search POD whitelist
Methods that weren't documented in the Perl bindings are made private.
commit 920a7dd81912ad6240d60a5e62ba2f87add9ecf9
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T11:36:33Z
Remove Store POD whitelist
Methods that weren't documented in the Perl bindings are made private.
commit fb6e42a79f6f5e6b5cb77d53d71ed8af481f6fbd
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T11:38:19Z
Remove Simple POD whitelist
commit 3e6b05ef81759581d822be4b26733f5149f58368
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T11:58:41Z
Remove LucyX POD whitelist
commit c6682c67a825b23f862c53880668e770bb13707c
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T13:00:03Z
Create Perl POD for Inversion
commit 04f1edf807ef11af0d956135042c8a6899bd98e0
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T13:46:14Z
Make I32Array public
Needed for C bindings.
commit 06b46a0dff6aaf224b6a2afe25181caefcfbc0c4
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T13:46:47Z
Make DataWriter_Add_Inverted_Doc private
The Inverter parameter isn't public.
commit f50a2fd58c864c926b07aaddb382fff68f0ae84a
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T13:47:52Z
Return Compiler instead of RangeCompiler
RangeCompiler isn't public.
commit 0e31a39d017060da75325ea05f8760545d3b69f9
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-23T13:48:56Z
Make Compiler_Highlight_Spans private
The DocVector parameter isn't public.
commit e3d1047fd399a2fb79995d37b26bc2817e27719e
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-25T10:07:28Z
Make Lucy::Analysis::Token public
commit 181ed13f0cb03ac8e7b9a9f59ab018bceb1cb086
Author: Nick Wellnhofer <we...@aevum.de>
Date: 2015-08-25T10:16:04Z
Remove links to private classes
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[lucy-dev] [GitHub] lucy pull request: Generate Perl POD from public methods
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/lucy/pull/18
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
Re: [lucy-dev] [GitHub] lucy pull request: Generate Perl POD from
public methods
Posted by Nick Wellnhofer <we...@aevum.de>.
On 09/09/2015 18:57, Nick Wellnhofer wrote:
> 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.
I committed the change to create POD for the first implementation of an
abstract method. This adds quite a few methods to the Perl documentation but I
think it's the right thing to do:
https://gist.github.com/nwellnhof/a1cb1b0d62f92d2d3fee
Otherwise it's impossible to tell from the documentation whether a class
implements an abstract method or not.
> 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.
I'm not sure whether POD for these methods should be added manually.
Nick
Re: [lucy-dev] [GitHub] lucy pull request: Generate Perl POD from
public methods
Posted by Nick Wellnhofer <we...@aevum.de>.
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
Re: [lucy-dev] [GitHub] lucy pull request: Generate Perl POD from
public methods
Posted by Marvin Humphrey <ma...@rectangular.com>.
On Thu, Aug 27, 2015 at 4:05 AM, nwellnhof <gi...@git.apache.org> wrote:
> GitHub user nwellnhof opened a pull request:
>
> https://github.com/apache/lucy/pull/18
>
> Generate Perl POD from public methods
>
> The Clownfish branch `perl_pod` adds POD for public novel methods by
> default, making it possible to remove the POD "whitelists".
>
> This branch also adds Perl documentation for Analyzer, Inversion, and
> Token, which is needed to write custom analyzers. It also removes
> documentation for some methods taking private classes as parameters.
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 documentation for several methods IndexSearcher inherits
from Searcher. Same with PolySearcher (though it's a less important
class).
* Restore Doc#add_fields.
* IndexReader#offsets became IndexReader#_offsets and should be restored.
* The PostingList methods Next, Advance, and Get_Doc_ID should become
public.
* Restore BitCollector#collect
* Restore ANDQuery#add_child and ORQuery#add_child.
Marvin Humphrey
--------------------------
Analyzer
add
transform
transform_text
dump
load
Inversion
add
new
append
next
reset
Token
add
new
get_text
set_text
get_start_offset
get_end_offset
get_boost
get_pos_inc
get_len
Doc # additions intentional, but add back get_fields
add
get_size
extract
field_names
remove
get_fields
DataWriter # intentional, not a big deal
remove
add_inverted_doc
DocReader # not a big deal
remove
aggregator
IndexReader
add
_offsets
remove
offsets
PostingList
remove
next
get_doc_id
advance
FieldType
add
set_indexed
set_boost
set_stored
set_sortable
ANDQuery
remove
add_child
BitCollector
remove
collect
Compiler
remove
highlight_spans
IndexSearcher
remove
hits
collect
doc_max
doc_freq
fetch_doc
get_schema
ORQuery
remove
add_child
PolyQuery
add
add_child
PolySearcher
remove
hits
doc_max
doc_freq
fetch_doc
get_schema
Query
add
dump
load
SortRule
add
get_type
Lock
add
shared