Lucene - Core
  1. Lucene - Core
  2. LUCENE-4010

AttributeSource api has broken documentation due to java generics bug

    Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: general/javadocs
    • Labels:
      None
    • Lucene Fields:
      New

      Description

      There seems to be a javadocs generation bug, whereby generic type params are not properly escaped. So if you use <A> as a type param (which we do in AttributeSource.java), it produces invalid HTML. The bug seems to be fixed in java 7...

      You can see the bug here (search for "after adding"):

      http://lucene.apache.org/core/old_versioned_docs/versions/3_5_0/api/all/org/apache/lucene/util/AttributeSource.html

      The <A> generic type is gone, and that closing paren is red but should be blue.

      The 3.6.0 javadocs are OK because we used java7 to generate them...

      I think we should avoid <A> to workaround it until we are on java 7...

        Activity

        Hide
        Robert Muir added a comment -

        The 3.6.0 javadocs are OK because we used java7 to generate them...

        Well not totally ok. Only OK on the website. The ones actually included in the release were generated
        with Java 5 (because i didnt want anything but a java5 compiler coming anywhere near the actual artifacts).

        The website javadocs were separately regenerated with java7: http://wiki.apache.org/lucene-java/HowToGenerateNiceJavadocs

        Show
        Robert Muir added a comment - The 3.6.0 javadocs are OK because we used java7 to generate them... Well not totally ok. Only OK on the website. The ones actually included in the release were generated with Java 5 (because i didnt want anything but a java5 compiler coming anywhere near the actual artifacts). The website javadocs were separately regenerated with java7: http://wiki.apache.org/lucene-java/HowToGenerateNiceJavadocs
        Hide
        Uwe Schindler added a comment - - edited

        I checked it, it always produces invalid HTML, you can use any type param you want. Same happens with <B>,... We should simply remove the @link and never use @link pointing to anything that uses generics.

        Show
        Uwe Schindler added a comment - - edited I checked it, it always produces invalid HTML, you can use any type param you want. Same happens with <B>,... We should simply remove the @link and never use @link pointing to anything that uses generics.
        Hide
        Michael McCandless added a comment -

        Hmm, true.

        But I think never linking to any API w/ generics is insanity (the cure is worse than the bug..). At least, the link works (it's just that the link text is missing the type param).

        So I think this is a WONTFIX...?

        Show
        Michael McCandless added a comment - Hmm, true. But I think never linking to any API w/ generics is insanity (the cure is worse than the bug..). At least, the link works (it's just that the link text is missing the type param). So I think this is a WONTFIX...?

          People

          • Assignee:
            Unassigned
            Reporter:
            Michael McCandless
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:

              Development