Differences between revisions 7 and 8
Revision 7 as of 2013-12-02 18:55:19
Size: 2392
Editor: UweSchindler
Comment: more warnings
Revision 8 as of 2013-12-03 11:55:41
Size: 2236
Editor: UweSchindler
Comment:
Deletions are marked like this. Additions are marked like this.
Line 17: Line 17:
 1. Under {{{lucene/}}}: {{{ant -Dversion=X.Y.Z -Djavadoc.noindex=false -Dbootclasspath=/path/to/the/minimum/java/jre/lib/rt.jar documentation}}} (important: the path after -Dbootclasspath must be absolute and without shell specials like ~ or $ENV, also validate the path: on Apple's JDK there is no rt.jar, the bootclasspath looks completely different)
 1. Under {{{solr/}}}: {{{ant -Dversion=X.Y.Z -Djavadoc.noindex=false -Dbootclasspath=/path/to/the/minimum/java/jre/lib/rt.jar documentation}}} (important: the path after -Dbootclasspath must be absolute and without shell specials like ~ or $ENV, also validate the path: on Apple's JDK there is no rt.jar, the bootclasspath looks completely different)
 1. Under {{{lucene/}}}: {{{ant -Dversion=X.Y.Z -Djavadoc.noindex=false -Dbootjdk=/path/to/the/minimum/jdk documentation}}}
 1. Under {{{solr/}}}: {{{ant -Dversion=X.Y.Z -Djavadoc.noindex=false -Dbootjdk=/path/to/the/minimum/jdk documentation}}}
Line 20: Line 20:
 1. IMPORTANT: Before deploying, check the correctness of newly generated Javadocs: For Lucene/Solr 4.x, the class org.apache.lucene.index.IndexReader has only "Closeable" but not "AutoCloseable" as interface (the latter would point to a 404 error on Oracle's side). In Lucene 5, AutoCloseable is fine.

Java 7 gives a nicer javadocs look and feel (less Geocities-like).

So you can optionally generate these nicer javadocs for the website without screwing anything else up, if you have the urge. The trick is you must use java7, but also have the minimal compiler version (e.g. java6 or whatever) so you can set your bootclasspath to its rt.jar (Apple's Java5 and Java6 JDKs call this file Classes/classes.jar instead - substitute in the cmdlines given below). This way the javadocs won't include any bogus java7 interfaces like AutoCloseable that don't actually apply.

In order to produce all of the documentation for a release, including a top level index, javadocs, changes, etc., use ant documentation under both lucene/ and solr/.

  1. When making the actual release, please always use the actual minimum compiler version!!!!

    E.g. if its java5, put an actually java5 compiler in your JAVA_HOME and then put $JAVA_HOME/bin in the front of your path. Although it might be safe to do otherwise, just do this and you don't need to worry.

  2. To make java7 javadocs for the website, first take your checkout of the release tag and clean old docs:
    • rm -rf solr/build/docs lucene/build/docs

  3. Next put a java7 compiler in your JAVA_HOME and $JAVA_HOME/bin in the front of your path.
  4. Under lucene/: ant -Dversion=X.Y.Z -Djavadoc.noindex=false -Dbootjdk=/path/to/the/minimum/jdk documentation

  5. Under solr/: ant -Dversion=X.Y.Z -Djavadoc.noindex=false -Dbootjdk=/path/to/the/minimum/jdk documentation

  6. Now you have fancy javadocs under lucene/build/docs/api and solr/build/docs/api, that otherwise link to the correct java versions and APIs, just look (hopefully) nicer.
  7. IMPORTANT: Before deploying, check the correctness of newly generated Javadocs: For Lucene/Solr 4.x, the class org.apache.lucene.index.IndexReader has only "Closeable" but not "AutoCloseable" as interface (the latter would point to a 404 error on Oracle's side). In Lucene 5, AutoCloseable is fine.

  8. Deploy these to the website instead of the ones from the RC. (someone could always volunteer to do that after the release really at any time)

HowToGenerateNiceJavadocs (last edited 2013-12-03 11:55:41 by UweSchindler)