ihji commented on a change in pull request #12071:
URL: https://github.com/apache/beam/pull/12071#discussion_r446413290
##########
File path:
runners/core-construction-java/src/test/java/org/apache/beam/runners/core/construction/ValidateRunnerXlangTest.java
##########
@@ -54,15 +60,36 @@
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;
-/** Test External transforms. */
+/**
+ * Runner Validation Test Suite for Cross-language Transforms.
+ *
+ * <p>As per Beams's Portability Framework design, Cross-language transforms
should work out of the
+ * box. In spite of this, there always exists a possibility of rough edges
existing. It could be
+ * caused due to unpolished implementation of any part of the execution code
path, for example:
+ *
+ * <ul>
+ * <li>Transform expansion [SDK]
+ * <li>Pipeline construction [SDK]
+ * <li>Cross-language artifact staging [Runner]
+ * <li>Language specific serialization/deserialization of PCollection (and
other data types)
+ * [Runner/SDK]
+ * </ul>
+ *
+ * <p>In an effort to improve developer visibility into potential problems,
this test suite
+ * validates a cross-language runner against <i>5 Core Beam transforms</i>
from any foreign language
Review comment:
Linking to Java transforms also conflicts with the description: from any
foreign language.
##########
File path:
runners/core-construction-java/src/test/java/org/apache/beam/runners/core/construction/ValidateRunnerXlangTest.java
##########
@@ -110,6 +137,20 @@ private void waitForReady() {
}
}
+ /**
+ * Motivation behind <i>singleInputOutputTest</i>.
+ *
+ * <ul>
Review comment:
Not sure whether we should use markup here since these comments will be
mostly read from the source code, not from the formatted doc pages (this class
doesn't create APIs, it's only for tests). Markups could hinder readability in
the raw form.
##########
File path:
runners/core-construction-java/src/test/java/org/apache/beam/runners/core/construction/ValidateRunnerXlangTest.java
##########
@@ -54,15 +60,36 @@
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;
-/** Test External transforms. */
+/**
+ * Runner Validation Test Suite for Cross-language Transforms.
+ *
+ * <p>As per Beams's Portability Framework design, Cross-language transforms
should work out of the
Review comment:
+1 for more direct and concise explanation.
----------------------------------------------------------------
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:
[email protected]
