You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@geode.apache.org by GitBox <gi...@apache.org> on 2022/04/15 05:31:23 UTC
[GitHub] [geode] DonalEvans opened a new pull request, #7594: GEODE-10023: Fix javadocs
DonalEvans opened a new pull request, #7594:
URL: https://github.com/apache/geode/pull/7594
This PR is intentionally broken up into two commits.
The first commit reduces the number of errors reported in the gradle
build log due to javadocs from over 3000 to 0. It also reduces the
number of warnings reported in the gradle build log due to javadocs
from over 3000 to 0.
After these changes, all published javadocs are now syntactically
correct, although no guarantee is made as to the content of the
documentation. Javadocs in classes that do not produce errors or
warnings in the gradle build log were not touched.
The changes made were:
- Add missing @return, @param and @throws tags
- Fix all errors due to incorrect HTML tag formatting
- Fix all errors due to improperly escaped characters
- Fix all broken @link tags
- Several minor spelling errors and typos fixed where spotted
The first commit comprises 546 files changed, 8498 insertions, and
3648 deletions, and as such, is not realistically reviewable. Given the
benefits of the clean-up and the low impact of any possible mistakes,
a "rubber-stamp" approval is requested form code owners in this case.
In the second commit, javadocs warnings and errors will be output in
the gradle build log, and if any are present, the build will fail.
This will enable developers to know if they have broken existing
javadocs, or if any javadocs they have added are incorrect.
<!-- Thank you for submitting a contribution to Apache Geode. -->
<!-- In order to streamline the review of the contribution we ask you
to ensure the following steps have been taken:
-->
### For all changes:
- [ ] Is there a JIRA ticket associated with this PR? Is it referenced in the commit message?
- [ ] Has your PR been rebased against the latest commit within the target branch (typically `develop`)?
- [ ] Is your initial contribution a single, squashed commit?
- [ ] Does `gradlew build` run cleanly?
- [ ] Have you written or updated unit tests to verify your changes?
- [ ] If adding new dependencies to the code, are these dependencies licensed in a way that is compatible for inclusion under [ASF 2.0](http://www.apache.org/legal/resolved.html#category-a)?
<!-- Note:
Please ensure that once the PR is submitted, check Concourse for build issues and
submit an update to your PR as soon as possible. If you need help, please send an
email to dev@geode.apache.org.
-->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] DonalEvans commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
DonalEvans commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851536969
##########
gradle/java.gradle:
##########
@@ -186,7 +186,7 @@ artifacts {
javadoc {
destinationDir = file("$buildDir/javadoc")
- options.addStringOption('Xdoclint:none', '-quiet')
+ options.addStringOption('Xwerror', '-quiet')
Review Comment:
If in-flight PRs are merged after this change and the build starts failing as a result of javadocs added by the PR being incorrect, the authors of those PRs should revert and fix the javadocs, or submit a second PR to fix the broken javadocs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] DonalEvans merged pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
DonalEvans merged PR #7594:
URL: https://github.com/apache/geode/pull/7594
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] DonalEvans commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
DonalEvans commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851535875
##########
geode-assembly/build.gradle:
##########
@@ -384,7 +384,7 @@ tasks.register('gfshDepsJar', Jar) {
tasks.register('docs', Javadoc) {
def docsDir = file("$buildDir/javadocs")
- options.addStringOption('Xdoclint:none', '-quiet')
+ options.addStringOption('Xwerror', '-quiet')
Review Comment:
No, the build currently passes, and will only fail if someone breaks existing javadocs or introduces new javadocs that have errors or warnings.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] agingade commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
agingade commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851535975
##########
gradle/java.gradle:
##########
@@ -186,7 +186,7 @@ artifacts {
javadoc {
destinationDir = file("$buildDir/javadoc")
- options.addStringOption('Xdoclint:none', '-quiet')
+ options.addStringOption('Xwerror', '-quiet')
Review Comment:
Will this be a issue with existing PRs?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] agingade commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
agingade commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851534074
##########
geode-assembly/build.gradle:
##########
@@ -384,7 +384,7 @@ tasks.register('gfshDepsJar', Jar) {
tasks.register('docs', Javadoc) {
def docsDir = file("$buildDir/javadocs")
- options.addStringOption('Xdoclint:none', '-quiet')
+ options.addStringOption('Xwerror', '-quiet')
Review Comment:
Does it break, cause failures for other devs/PRs?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] DonalEvans commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
DonalEvans commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851535875
##########
geode-assembly/build.gradle:
##########
@@ -384,7 +384,7 @@ tasks.register('gfshDepsJar', Jar) {
tasks.register('docs', Javadoc) {
def docsDir = file("$buildDir/javadocs")
- options.addStringOption('Xdoclint:none', '-quiet')
+ options.addStringOption('Xwerror', '-quiet')
Review Comment:
No, the build currently passes, and will only fail if someone breaks existing javadocs or introduces new javadocs that have errors or warnings. Since we shouldn't be introducing javadoc warnings or errors, making it a requirement that they be fixed seems like a good idea.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] DonalEvans commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
DonalEvans commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851529891
##########
geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/session/tests/ContainerInstall.java:
##########
@@ -248,32 +252,36 @@ int getDefaultLocatorPort() {
return defaultLocatorPort;
}
- /**
+ /*
* Gets the cache XML file to use by default for this installation
*/
File getCacheXMLFile() {
return new File(modulePath + "/conf/" + getConnectionType().getCacheXMLFileName());
}
- /**
+ /*
* Cargo specific string to identify the container with
*/
public abstract String getInstallId();
- /**
+ /*
* A human readable description of the installation
*/
public abstract String getInstallDescription();
- /**
+ /*
* Get the session manager class to use
*/
public abstract String getContextSessionManagerClass();
/**
* Generates a {@link ServerContainer} from the given {@link ContainerInstall}
*
+ * @param containerConfigHome The folder that the container configuration folder should be setup
Review Comment:
How do you mean?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] gesterzhou commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
gesterzhou commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851528925
##########
geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/session/tests/ContainerInstall.java:
##########
@@ -248,32 +252,36 @@ int getDefaultLocatorPort() {
return defaultLocatorPort;
}
- /**
+ /*
* Gets the cache XML file to use by default for this installation
*/
File getCacheXMLFile() {
return new File(modulePath + "/conf/" + getConnectionType().getCacheXMLFileName());
}
- /**
+ /*
* Cargo specific string to identify the container with
*/
public abstract String getInstallId();
- /**
+ /*
* A human readable description of the installation
*/
public abstract String getInstallDescription();
- /**
+ /*
* Get the session manager class to use
*/
public abstract String getContextSessionManagerClass();
/**
* Generates a {@link ServerContainer} from the given {@link ContainerInstall}
*
+ * @param containerConfigHome The folder that the container configuration folder should be setup
Review Comment:
these 2 lines can be adjusted
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [geode] agingade commented on a diff in pull request #7594: GEODE-10023: Fix javadocs
Posted by GitBox <gi...@apache.org>.
agingade commented on code in PR #7594:
URL: https://github.com/apache/geode/pull/7594#discussion_r851535975
##########
gradle/java.gradle:
##########
@@ -186,7 +186,7 @@ artifacts {
javadoc {
destinationDir = file("$buildDir/javadoc")
- options.addStringOption('Xdoclint:none', '-quiet')
+ options.addStringOption('Xwerror', '-quiet')
Review Comment:
Will this be an issue with existing PRs?
What if the new PRs merged with java doc issues.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@geode.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org