Don't inheritDoc from JDK

[GoogleCodeExporter]

{@inheritDoc} is great to reuse doc between our own classes, but inheriting
docs from the JDK is less of a win.

- to build the library properly, ant needs to know where to find JDK
sources, which not everyone has, or has unzipped in the expected place
- we have to see hundreds of JDK javadoc warnings in our build
- what is seen in our docs will change depending on what JDK was pointed at
- since JDK docs don't change that often anyway, it doesn't buy much
- things will become easier to understand when looking at the code itself
- in some cases we can even refine/clean up/tweak the docs to better suit
our users.

Original issue reported on code.google.com by kevin...@gmail.com on 6 Jun 2008 at 7:46

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 18 Mar 2009 at 2:20

• Removed labels: 1.0

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 15 Jun 2009 at 5:42

• Added labels: 1.0

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 17 Sep 2009 at 5:45

• Added labels: Milestone-1.0

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 17 Sep 2009 at 5:46

• Removed labels: 1.0

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 17 Sep 2009 at 6:01

• Added labels: Type-Docs

[GoogleCodeExporter]

I think this fix will be too painful and time-consuming.

Instead, I've now fixed build.xml to use $JAVA_HOME/src in its sourcepath for 
generating javadoc. So users will have to have an unzipped src directory in 
order to 
build. For our own builds, we will always build javadoc against our latest 
openJDK 
sources, and this should be the highest-quality JDK docs we can use.  Users who 
build 
against a different JDK may get different-looking javadoc results, true.

When building we see 11 warnings, which is annoying, but oh well.

The on-line generated javadoc is sooo much better now.

Original comment by kevin...@gmail.com on 17 Sep 2009 at 6:33

• Changed state: WontFix