Lucene - Core
  1. Lucene - Core
  2. LUCENE-4894

Facet User Guide for lucene 4.2 has deleted classes/methods and needs more explanations.

    Details

    • Lucene Fields:
      New, Patch Available

      Description

      • Concurrent Indexing and Search
        There is no clear explanation regarding those points below.
        1. TaxonomyReader should be reopened after IndexReader.
        2. TaxonomyWriter should be committed before IndexWriter. TaxonomyWriter should be closed before IndexWriter.
        The rationale is that it's ok to see categories to which no document belongs but not ok the other way around.
        Beginners may not be able to see this until after they think through it for a long time, which most of them including me wouldn't do.
        However, facet user guide doesn't explain the rationale clearly.
      • DocumentBuilder & FacetSearchParams.addFacetRequest
        They no longer exist in lucene 4.2, but they are used in code examples.
      • FacetResultNode.getLabel(TaxonomyReader)
        It doesn't eixst in 4.2, but it is mentioned in "Multiple Facet Requests"
      • ETC
        I don't know if there are other points to be made.

        Issue Links

          Activity

          Hide
          Shai Erera added a comment -

          The userguide is seriously outdated after all the recent refactoring. I was wondering if we should keep it at all, or rather include a high-level documentation under o.a.l.facet.package.html which covers the basic points, and then focus on maintaining good javadocs at the classes / packages level. It gets harder to maintain these documents ...

          Nevertheless, if you want to take a crack at improving / fixing it, I will help you get it in.

          Show
          Shai Erera added a comment - The userguide is seriously outdated after all the recent refactoring. I was wondering if we should keep it at all, or rather include a high-level documentation under o.a.l.facet.package.html which covers the basic points, and then focus on maintaining good javadocs at the classes / packages level. It gets harder to maintain these documents ... Nevertheless, if you want to take a crack at improving / fixing it, I will help you get it in.
          Hide
          crocket added a comment -

          Including documentations in javadocs might do the job.

          Show
          crocket added a comment - Including documentations in javadocs might do the job.
          Hide
          Michael McCandless added a comment -

          +1 to remove the userGuide and absorb it into javadocs.

          Show
          Michael McCandless added a comment - +1 to remove the userGuide and absorb it into javadocs.
          Hide
          crocket added a comment - - edited

          However, without facet user guide, I wouldn't have known that it ever existed.
          You may still need to advertise the facet module in http://lucene.apache.org/core/4_x_x/index.html
          It's good to leave an advertisement in the core index page.

          Show
          crocket added a comment - - edited However, without facet user guide, I wouldn't have known that it ever existed. You may still need to advertise the facet module in http://lucene.apache.org/core/4_x_x/index.html It's good to leave an advertisement in the core index page.
          Hide
          Shai Erera added a comment -

          I removed the userguide completely, put links to my two blog posts which give an overview of the module, as well as links to demo code. I modified some package.htmls, but I didn't absorb the entire userguide into them because many parts of it were outdated. I'm rather skeptic we'll be able to maintain the jdocs updated in blogs, package.html and java classes. So for now I think we should focus on making sure the classes are well (and accurately) documented.

          Show
          Shai Erera added a comment - I removed the userguide completely, put links to my two blog posts which give an overview of the module, as well as links to demo code. I modified some package.htmls, but I didn't absorb the entire userguide into them because many parts of it were outdated. I'm rather skeptic we'll be able to maintain the jdocs updated in blogs, package.html and java classes. So for now I think we should focus on making sure the classes are well (and accurately) documented.
          Hide
          Michael McCandless added a comment -

          +1

          Show
          Michael McCandless added a comment - +1
          Hide
          ASF subversion and git services added a comment -

          Commit 1505041 from Shai Erera in branch 'dev/trunk'
          [ https://svn.apache.org/r1505041 ]

          LUCENE-4894: remove facet userguide

          Show
          ASF subversion and git services added a comment - Commit 1505041 from Shai Erera in branch 'dev/trunk' [ https://svn.apache.org/r1505041 ] LUCENE-4894 : remove facet userguide
          Hide
          ASF subversion and git services added a comment -

          Commit 1505047 from Shai Erera in branch 'dev/branches/branch_4x'
          [ https://svn.apache.org/r1505047 ]

          LUCENE-4894: remove facet userguide

          Show
          ASF subversion and git services added a comment - Commit 1505047 from Shai Erera in branch 'dev/branches/branch_4x' [ https://svn.apache.org/r1505047 ] LUCENE-4894 : remove facet userguide
          Hide
          Shai Erera added a comment -

          Removed in both 5.0 and 4.x. Thanks crocket for reporting!

          Show
          Shai Erera added a comment - Removed in both 5.0 and 4.x. Thanks crocket for reporting!
          Hide
          ASF subversion and git services added a comment -

          Commit 1505075 from Robert Muir in branch 'dev/trunk'
          [ https://svn.apache.org/r1505075 ]

          LUCENE-4894: remove dead link to user guide

          Show
          ASF subversion and git services added a comment - Commit 1505075 from Robert Muir in branch 'dev/trunk' [ https://svn.apache.org/r1505075 ] LUCENE-4894 : remove dead link to user guide
          Hide
          ASF subversion and git services added a comment -

          Commit 1505076 from Robert Muir in branch 'dev/branches/branch_4x'
          [ https://svn.apache.org/r1505076 ]

          LUCENE-4894: remove dead link to user guide

          Show
          ASF subversion and git services added a comment - Commit 1505076 from Robert Muir in branch 'dev/branches/branch_4x' [ https://svn.apache.org/r1505076 ] LUCENE-4894 : remove dead link to user guide
          Hide
          Adrien Grand added a comment -

          4.5 release -> bulk close

          Show
          Adrien Grand added a comment - 4.5 release -> bulk close

            People

            • Assignee:
              Shai Erera
              Reporter:
              crocket
            • Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development