disable doclint #38
disable doclint #38
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR disables doclint checking during Javadoc generation by adding the -Xdoclint:none argument to all javadoc tasks in the Ant build file. It also removes the Java version requirement from the javadocs target description and eliminates an extraneous blank line.
- Adds
-Xdoclint:noneargument to five javadoc tasks to suppress documentation linting - Updates javadocs target description to remove outdated Java version requirement
- Removes unnecessary blank line in the build file
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| > | ||
| <arg value="-Xdoclint:none"/> | ||
| </javadoc> |
There was a problem hiding this comment.
[nitpick] The indentation of the <arg> element is inconsistent with the surrounding XML structure. The <arg> element should be indented to align with other child elements of the <javadoc> tag. Consider using consistent indentation (typically 2 or 4 spaces per level) throughout all javadoc tasks.
| > | ||
| <arg value="-Xdoclint:none"/> | ||
| </javadoc> |
There was a problem hiding this comment.
[nitpick] The indentation of the <arg> element is inconsistent with the surrounding XML structure. The <arg> element should be indented to align with other child elements of the <javadoc> tag. Consider using consistent indentation (typically 2 or 4 spaces per level) throughout all javadoc tasks.
| > | ||
| <arg value="-Xdoclint:none"/> | ||
| </javadoc> |
There was a problem hiding this comment.
[nitpick] The indentation of the <arg> element is inconsistent with the surrounding XML structure. The <arg> element should be indented to align with other child elements of the <javadoc> tag. Consider using consistent indentation (typically 2 or 4 spaces per level) throughout all javadoc tasks.
| > | ||
| <arg value="-Xdoclint:none"/> | ||
| </javadoc> |
There was a problem hiding this comment.
[nitpick] The indentation of the <arg> element is inconsistent with the surrounding XML structure. The <arg> element should be indented to align with other child elements of the <javadoc> tag. Consider using consistent indentation (typically 2 or 4 spaces per level) throughout all javadoc tasks.
| > | ||
| <arg value="-Xdoclint:none"/> | ||
| </javadoc> |
There was a problem hiding this comment.
[nitpick] The indentation of the <arg> element is inconsistent with the surrounding XML structure. The <arg> element should be indented to align with other child elements of the <javadoc> tag. Consider using consistent indentation (typically 2 or 4 spaces per level) throughout all javadoc tasks.
| additionalparam='${additional.param}' | ||
| /> | ||
| > | ||
| <arg value="-Xdoclint:none"/> |
There was a problem hiding this comment.
Setting -Xdoclint:none for javax.xml.*,org.w3c.*,org.xml.* is reasonable but for the packages under org.apache.xerces it should really be -Xdoclint:all (perhaps -Xdoclint:all -Xdoclint:-missing is reasonable).
Also it would be preferable to set the following on the xerces code:
failonerror='yes'
failonwarning='yes'
these Javadoc issues can be resolved with minimal effort. A lot of the errors are just invalid html in classes like EncodingMap. As for the warnings, as long as publicly accessible methods have all params and return values documented then it should be acceptable. Potentially failonwarning could be no as long as those things are covered
|
Failing on existing Javadoc errors is a hard no. These problems do not break the build and they should not block shipping. I am unwilling to revert the product to an unshippable state. Feel free to improve things, but we must not break the build. Right now the build is too noisy. These warnings aren't very significant, sio I don;t them hiding other more serious problems. |
|
I'm not suggesting failing builds now. I'm suggesting fixing the problems then merging this. |
|
A lot of these doclint issues are gone and some of the remaining ones can probably be tackled fairly easily. One issue that creates a lot of errors is that numerous methods (x19) have been documented with I can make PRs for these problems, after that then there's just a few leftover errors:
there's warnings, but that's not so much of a problem. Having |
2 participants
No description provided.