You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by GitBox <gi...@apache.org> on 2021/03/24 02:58:30 UTC

[GitHub] [kafka] vvcephei opened a new pull request #10392: KAFKA-12435: Fix javadoc errors

vvcephei opened a new pull request #10392:
URL: https://github.com/apache/kafka/pull/10392


   Fixes errors while generating javadoc.
   
   ### Committer Checklist (excluded from commit message)
   - [ ] Verify design and implementation 
   - [ ] Verify test coverage and CI build status
   - [ ] Verify documentation (including upgrade notes)
   


-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] ijuma commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
ijuma commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600450380



##########
File path: streams/test-utils/src/main/java/org/apache/kafka/streams/test/internal/KeyValueStoreFacade.java
##########
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.kafka.streams.internals;
+package org.apache.kafka.streams.test.internal;

Review comment:
       It's not great that we use `internal` here and `internals` everywhere else. I think you did this to avoid the javadoc exclusion pattern, but...




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600548484



##########
File path: streams/test-utils/src/main/java/org/apache/kafka/streams/test/internal/KeyValueStoreFacade.java
##########
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.kafka.streams.internals;
+package org.apache.kafka.streams.test.internal;

Review comment:
       Yes, that's exactly right. I agree it's not great. Maybe a better alternative is to just not try to mark these classes as "internal". It should be pretty hard to get confused about their usage, and apparently we have to include them in the Javadoc anyway, so it's probably fine to just move them up a level and drop `internal`




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei commented on pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei commented on pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#issuecomment-806067123


   Ok, I've tested this fix locally, and it looks like, although we have some flaky test failures, the builds are still functioning.


-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei commented on pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei commented on pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#issuecomment-805986023


   Ok, thanks for the reviews, @ijuma and @chia7712 !
   
   I decided that instead of playing subtle games with the pattern matching and the package name, I'll just make these classes into static inner classes of TopologyTestDriver (their only usage).
   
   I double-checked the generated javadoc, and I don't see anything suspicious either in the package tree or in the TopologyTestDriver.html doc.


-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei merged pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei merged pull request #10392:
URL: https://github.com/apache/kafka/pull/10392


   


-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600124984



##########
File path: clients/src/main/java/org/apache/kafka/server/log/remote/storage/RemoteLogMetadataManager.java
##########
@@ -71,7 +71,7 @@
      * <p>
      * <pre>
      * +---------------------+            +----------------------+
-     * |COPY_SEGMENT_STARTED |----------->|COPY_SEGMENT_FINISHED |
+     * |COPY_SEGMENT_STARTED |-----------&gt;|COPY_SEGMENT_FINISHED |

Review comment:
       These were just warnings, but they were the only two warnings in the project, so I fixed them. We just need to XML-escape the `>` character.

##########
File path: streams/test-utils/src/main/java/org/apache/kafka/streams/TopologyTestDriver.java
##########
@@ -41,8 +41,8 @@
 import org.apache.kafka.common.utils.Time;
 import org.apache.kafka.streams.errors.LogAndContinueExceptionHandler;
 import org.apache.kafka.streams.errors.TopologyException;
-import org.apache.kafka.streams.internals.KeyValueStoreFacade;
-import org.apache.kafka.streams.internals.WindowStoreFacade;
+import org.apache.kafka.streams.test.internal.KeyValueStoreFacade;
+import org.apache.kafka.streams.test.internal.WindowStoreFacade;

Review comment:
       Javadoc is unable to generate docs for this (TopologyTestDriver) file because it depends on these classes, which are also in test-utils, but are excluded in the build.gradle spec.
   
   I was unable to override the exclusion with a more specific inclusion, so instead I just moved these classes to a different package that matches only the "include" patterns in `:streams:test-utils:javadoc`.

##########
File path: streams/src/main/java/org/apache/kafka/streams/processor/internals/StreamsProducer.java
##########
@@ -237,7 +237,7 @@ private static boolean isRecoverable(final KafkaException uncaughtException) {
      * @throws IllegalStateException if EOS is disabled
      * @throws TaskMigratedException
      */
-    void commitTransaction(final Map<TopicPartition, OffsetAndMetadata> offsets,
+    protected void commitTransaction(final Map<TopicPartition, OffsetAndMetadata> offsets,

Review comment:
       Needed this so I could move the subclass to a different package. I think it's still just as obviously inappropriate for users to subclass this class, since it's in the `internals` package.




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] ijuma commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
ijuma commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600450380



##########
File path: streams/test-utils/src/main/java/org/apache/kafka/streams/test/internal/KeyValueStoreFacade.java
##########
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.kafka.streams.internals;
+package org.apache.kafka.streams.test.internal;

Review comment:
       It's not great that we use `internal` here and `internals` everywhere else.




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600715320



##########
File path: build.gradle
##########
@@ -1622,7 +1622,6 @@ project(':streams:test-utils') {
 
   javadoc {
     include "**/org/apache/kafka/streams/test/**"
-    exclude "**/org/apache/kafka/streams/internals/**", "**/org/apache/kafka/streams/**/internals/**"

Review comment:
       The files I converted to static inner classes were the only contents of these packages, so they don't exist anymore. I figured I'd go ahead and remove the exclusion, too.




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] ijuma commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
ijuma commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600449913



##########
File path: streams/test-utils/src/main/java/org/apache/kafka/streams/TopologyTestDriver.java
##########
@@ -41,8 +41,8 @@
 import org.apache.kafka.common.utils.Time;
 import org.apache.kafka.streams.errors.LogAndContinueExceptionHandler;
 import org.apache.kafka.streams.errors.TopologyException;
-import org.apache.kafka.streams.internals.KeyValueStoreFacade;
-import org.apache.kafka.streams.internals.WindowStoreFacade;
+import org.apache.kafka.streams.test.internal.KeyValueStoreFacade;
+import org.apache.kafka.streams.test.internal.WindowStoreFacade;

Review comment:
       Have you checked that the produced javadoc does not include these internal files?




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] chia7712 commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
chia7712 commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600696771



##########
File path: build.gradle
##########
@@ -1622,7 +1622,6 @@ project(':streams:test-utils') {
 
   javadoc {
     include "**/org/apache/kafka/streams/test/**"
-    exclude "**/org/apache/kafka/streams/internals/**", "**/org/apache/kafka/streams/**/internals/**"

Review comment:
       As the related class have be moved from `internals`, does it need to remove this `exclude` rule?




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] vvcephei commented on a change in pull request #10392: KAFKA-12435: Fix javadoc errors

Posted by GitBox <gi...@apache.org>.
vvcephei commented on a change in pull request #10392:
URL: https://github.com/apache/kafka/pull/10392#discussion_r600666375



##########
File path: streams/test-utils/src/main/java/org/apache/kafka/streams/TopologyTestDriver.java
##########
@@ -41,8 +41,8 @@
 import org.apache.kafka.common.utils.Time;
 import org.apache.kafka.streams.errors.LogAndContinueExceptionHandler;
 import org.apache.kafka.streams.errors.TopologyException;
-import org.apache.kafka.streams.internals.KeyValueStoreFacade;
-import org.apache.kafka.streams.internals.WindowStoreFacade;
+import org.apache.kafka.streams.test.internal.KeyValueStoreFacade;
+import org.apache.kafka.streams.test.internal.WindowStoreFacade;

Review comment:
       I didn't before, but I did just check on my latest strategy, and they are not generated.




-- 
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org