Lucene - Core
  1. Lucene - Core
  2. LUCENE-1862

duplicate package.html files in queryParser and analsysis.cn packages

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.9
    • Component/s: None
    • Labels:
      None
    • Lucene Fields:
      New

      Description

      These files conflict with eachother when building the javadocs. there can be only one (of each) ...

      hossman@brunner:~/lucene/java$ find src contrib -name package.html | perl -ple 's{.*src/java/}{}' | sort | uniq -c | grep -v " 1 "
         2 org/apache/lucene/analysis/cn/package.html
         2 org/apache/lucene/queryParser/package.html
      hossman@brunner:~/lucene/java$ find src contrib -path \*queryParser/package.html
      src/java/org/apache/lucene/queryParser/package.html
      contrib/queryparser/src/java/org/apache/lucene/queryParser/package.html
      hossman@brunner:~/lucene/java$ find src contrib -path \*cn/package.html
      contrib/analyzers/common/src/java/org/apache/lucene/analysis/cn/package.html
      contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/package.html
      
      1. LUCENE-1862.patch
        20 kB
        Robert Muir
      2. LUCENE-1862-queryParser.patch
        13 kB
        Hoss Man

        Activity

        Hide
        Mark Miller added a comment -

        Anyone have any thoughts here? Any time I think about it, I just end up thinking its best to leave it ... the javadoc itself (package descriptions) still appears to come out correctly.

        Show
        Mark Miller added a comment - Anyone have any thoughts here? Any time I think about it, I just end up thinking its best to leave it ... the javadoc itself (package descriptions) still appears to come out correctly.
        Hide
        Robert Muir added a comment -

        just stating the obvious, but for the analysis.cn, the problem is that I think we want javadocs in

        • analyzers javadocs jar
        • smartcn javadocs jar
        • javadocs-all target (which one?, this is causing the error)

        it would be nice not to have the error, but also still have package.html in all 3. any ideas?
        the whole point of the package.html in this case is to help users figure out what all the chinese analysis options are...

        Show
        Robert Muir added a comment - just stating the obvious, but for the analysis.cn, the problem is that I think we want javadocs in analyzers javadocs jar smartcn javadocs jar javadocs-all target (which one?, this is causing the error) it would be nice not to have the error, but also still have package.html in all 3. any ideas? the whole point of the package.html in this case is to help users figure out what all the chinese analysis options are...
        Hide
        Uwe Schindler added a comment -

        How about putting the package.html files one level lower into the smartcn package? the package.html of the top-level analyzers's doc could then be only in the common contrib.

        Show
        Uwe Schindler added a comment - How about putting the package.html files one level lower into the smartcn package? the package.html of the top-level analyzers's doc could then be only in the common contrib.
        Hide
        Robert Muir added a comment -

        Uwe, i think you are right, but the real problem in this case is that SmartChineseAnalyzer is not in the smartcn package.

        it is under o.a.l.analysis instead of o.a.l.analysis.smartcn (with all the other smartcn tokenizer/tokenfilters where it should really belong imho)

        if we put package.html and SmartChineseAnalyzer one level lower, things would make more sense in my opinion.

        Show
        Robert Muir added a comment - Uwe, i think you are right, but the real problem in this case is that SmartChineseAnalyzer is not in the smartcn package. it is under o.a.l.analysis instead of o.a.l.analysis.smartcn (with all the other smartcn tokenizer/tokenfilters where it should really belong imho) if we put package.html and SmartChineseAnalyzer one level lower, things would make more sense in my opinion.
        Hide
        Uwe Schindler added a comment -

        +1

        I was wondering why the analyzer is not in the sub-package. I think we can change this even in release phase (as the whole package is experimental...)

        Show
        Uwe Schindler added a comment - +1 I was wondering why the analyzer is not in the sub-package. I think we can change this even in release phase (as the whole package is experimental...)
        Hide
        Mark Miller added a comment -

        I think we can change this even in release phase (as the whole package is experimental...)

        +1

        Show
        Mark Miller added a comment - I think we can change this even in release phase (as the whole package is experimental...) +1
        Hide
        Mark Miller added a comment -

        Just as an expansion on my feelings about any changes:

        I posted the rules that are suggested on the wiki - but I think they are a bit harsh (eg only serious bug fixes). My thought is that the important part is :

        Keep in mind that it is our main intention to keep the branch as stable as possible.

        I think that anything is fair game as long as its clear it will not affect stability. If everybody thinks something is a good idea, and they don't think it has the reach to affect stability (or undercut the testing that has already occured), I don't see why we wouldn't do it. As long as its discussed first and given a bit of time to ensure consensus.

        Show
        Mark Miller added a comment - Just as an expansion on my feelings about any changes: I posted the rules that are suggested on the wiki - but I think they are a bit harsh (eg only serious bug fixes). My thought is that the important part is : Keep in mind that it is our main intention to keep the branch as stable as possible. I think that anything is fair game as long as its clear it will not affect stability. If everybody thinks something is a good idea, and they don't think it has the reach to affect stability (or undercut the testing that has already occured), I don't see why we wouldn't do it. As long as its discussed first and given a bit of time to ensure consensus.
        Hide
        Robert Muir added a comment -

        patch for the smartcn issue.

        mkdir contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/smart
        svn add contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/smart
        svn move contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/TestSmartChineseAnalyzer.java contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/smart
        svn move contrib/analyzers/smartcn/src/resources/org/apache/lucene/analysis/cn/stopwords.txt contrib/analyzers/smartcn/src/resources/org/apache/lucene/analysis/cn/smart
        svn move contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/SmartChineseAnalyzer.java contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/smart
        svn delete contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/smart/package.html
        svn move contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/package.html contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/smart
        patch -p0 < patch.txt 
        

        note: i did not make any change to analysis/cn/smart/hhmm/package.html, although it should be modified like the other files. the problem is it has a stray control-M, (as well as not having eol-style set), so it is impossible for me to provide a well-formed patch that will actually apply. we should fix this in the future!

        Show
        Robert Muir added a comment - patch for the smartcn issue. mkdir contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/smart svn add contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/smart svn move contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/TestSmartChineseAnalyzer.java contrib/analyzers/smartcn/src/test/org/apache/lucene/analysis/cn/smart svn move contrib/analyzers/smartcn/src/resources/org/apache/lucene/analysis/cn/stopwords.txt contrib/analyzers/smartcn/src/resources/org/apache/lucene/analysis/cn/smart svn move contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/SmartChineseAnalyzer.java contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/smart svn delete contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/smart/package.html svn move contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/package.html contrib/analyzers/smartcn/src/java/org/apache/lucene/analysis/cn/smart patch -p0 < patch.txt note: i did not make any change to analysis/cn/smart/hhmm/package.html, although it should be modified like the other files. the problem is it has a stray control-M, (as well as not having eol-style set), so it is impossible for me to provide a well-formed patch that will actually apply. we should fix this in the future!
        Hide
        Hoss Man added a comment -

        Anyone have any thoughts here? Any time I think about it, I just end up thinking its best to leave it ... the javadoc itself (package descriptions) still appears to come out correctly.

        Uh ... not really. what you get is non-deterministic behavior, where one of the package.html files for each package gets picked, and the other one isn't used. (this can look particularly confusing with something like queryPrser, where you'll find one description in the "core" docs, a differnet version in the "contrib" docs, and it's a crap shoot as to which one of those will show up in the "all" docs.

        Show
        Hoss Man added a comment - Anyone have any thoughts here? Any time I think about it, I just end up thinking its best to leave it ... the javadoc itself (package descriptions) still appears to come out correctly. Uh ... not really. what you get is non-deterministic behavior, where one of the package.html files for each package gets picked, and the other one isn't used. (this can look particularly confusing with something like queryPrser, where you'll find one description in the "core" docs, a differnet version in the "contrib" docs, and it's a crap shoot as to which one of those will show up in the "all" docs.
        Hide
        Hoss Man added a comment -

        Robert: i opened LUCENE-1882 to track the issue of moving SmartChineseAnalyzer into the correct package, and committed your suggested changes under that issue.

        i know for a fact that part of your patch didn't make it in – the characters kept getting corrupted in one of hte package.html files, and i couldn't figure out an obvious reason/solution so i just committed what there was at that point so we'd at least have all the files in the right places to move forward from there.

        please take a look at the current state of the pacakge.html files and let us konw what still needs done to make them "good"

        Show
        Hoss Man added a comment - Robert: i opened LUCENE-1882 to track the issue of moving SmartChineseAnalyzer into the correct package, and committed your suggested changes under that issue. i know for a fact that part of your patch didn't make it in – the characters kept getting corrupted in one of hte package.html files, and i couldn't figure out an obvious reason/solution so i just committed what there was at that point so we'd at least have all the files in the right places to move forward from there. please take a look at the current state of the pacakge.html files and let us konw what still needs done to make them "good"
        Hide
        Hoss Man added a comment -

        FYI: the queryParser contrib doesn't even have any classes living in the org.apache.lucene.queryParser package, so contrib/queryparser/src/java/org/apache/lucene/queryParser/package.html is never even used when building the contrib-queryParser specific javadocs ... it's just a possible candidate when builidng the "all" javadocs.

        the best solution seems to be moving that content into contrib/queryParser/src/java/overview.html ... i'll work up a patch.

        Show
        Hoss Man added a comment - FYI: the queryParser contrib doesn't even have any classes living in the org.apache.lucene.queryParser package, so contrib/queryparser/src/java/org/apache/lucene/queryParser/package.html is never even used when building the contrib-queryParser specific javadocs ... it's just a possible candidate when builidng the "all" javadocs. the best solution seems to be moving that content into contrib/queryParser/src/java/overview.html ... i'll work up a patch.
        Hide
        Hoss Man added a comment -

        patch fixing the duplicate package.html files for queryParser by moving the contrib version into the contrib's overview.html (the package one was never used in the contrib specific docs)

        this patch also makes some other misc improvements to the docs, and tweaks the build.xml so that the appropraite subpackages are listed in the correct section.

        Show
        Hoss Man added a comment - patch fixing the duplicate package.html files for queryParser by moving the contrib version into the contrib's overview.html (the package one was never used in the contrib specific docs) this patch also makes some other misc improvements to the docs, and tweaks the build.xml so that the appropraite subpackages are listed in the correct section.
        Hide
        Hoss Man added a comment -

        LUCENE-1862-queryParser.patch ...

        Committed revision 810286

        Show
        Hoss Man added a comment - LUCENE-1862 -queryParser.patch ... Committed revision 810286
        Hide
        Hoss Man added a comment -

        this is done ... if people want to make other improvements to the javadocs for either package, let's open separate issues.

        Show
        Hoss Man added a comment - this is done ... if people want to make other improvements to the javadocs for either package, let's open separate issues.

          People

          • Assignee:
            Hoss Man
            Reporter:
            Hoss Man
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development