Re: [PR] CASSJAVA-109, CASSJAVA-117: Manual and API References after donation, Build CI for Java Driver Doc: [cassandra-java-driver]

["absurdfarce (via GitHub)" <gi...@apache.org>]

absurdfarce commented on code in PR #2063:
URL: https://github.com/apache/cassandra-java-driver/pull/2063#discussion_r3018940038


##########
pom.xml:
##########
@@ -882,7 +899,49 @@ limitations under the License.]]></inlineHeader>
               <useStandardDocletOptions>false</useStandardDocletOptions>
             </configuration>
           </execution>
+          <execution>
+            <!-- Generate aggregated Javadoc for specified modules -->
+            <id>aggregate-javadoc</id>
+            <goals>
+              <goal>aggregate</goal>
+            </goals>
+            <phase>site</phase>
+            <configuration>
+              <includeDependencySources>false</includeDependencySources>
+              <dependencySourceIncludes>
+                <dependencySourceInclude>org.apache.cassandra:java-driver-core</dependencySourceInclude>
+                <dependencySourceInclude>org.apache.cassandra:java-driver-query-builder</dependencySourceInclude>
+                <dependencySourceInclude>org.apache.cassandra:java-driver-mapper-runtime</dependencySourceInclude>
+              </dependencySourceIncludes>
+              <reactorProjects>
+                <reactorProject>core</reactorProject>
+                <reactorProject>query-builder</reactorProject>
+                <reactorProject>mapper-runtime</reactorProject>
+              </reactorProjects>
+              <doctitle>Apache Cassandra Java Driver ${project.version} API</doctitle>
+              <bottom><![CDATA[
+                Copyright &#169; {inceptionYear}&#x2013;{currentYear} <a href="https://www.apache.org/">The Apache Software Foundation</a>. All rights reserved.
+                ]]></bottom>
+            </configuration>
+          </execution>
         </executions>
+        <dependencies>
+          <dependency>
+            <groupId>com.google.errorprone</groupId>
+            <artifactId>error_prone_annotations</artifactId>
+            <version>2.3.4</version>
+          </dependency>
+          <dependency>
+            <groupId>com.github.stephenc.jcip</groupId>
+            <artifactId>jcip-annotations</artifactId>
+            <version>1.0-1</version>
+          </dependency>
+          <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs-annotations</artifactId>

Review Comment:
   Hmmm, I _thought_ this got taken out as a side effect of some other work that was done... but I can't find that change now.  Perhaps more importantly it looks like these dependencies are [still in 4.x](https://github.com/apache/cassandra-java-driver/blame/4.x/pom.xml) and apparently have been for some time.



##########
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java:
##########
@@ -1022,8 +1022,8 @@ public enum DefaultDriverOption implements DriverOption {
    * }
    * </pre>
    *
-   * Note: subnets must be represented as prefix blocks, see {@link
-   * inet.ipaddr.Address#isPrefixBlock()}.
+   * Note: subnets must be represented as prefix blocks, see <a
+   * href="https://javadoc.io/doc/com.github.seancfoley/ipaddress/latest/inet/ipaddr/Address.html#isPrefixBlock--">inet.ipaddr.Address.isPrefixBlock()</a>

Review Comment:
   Perhaps not related to this change but this link... offers very little information about what a prefix block is.  The text literally reads "Returns whether the address range has a prefix length and includes the block of values for its prefix length.", which isn't super-descriptive.
   
   We'd prolly be better pointing users at something from the manual, something like https://seancfoley.github.io/IPAddress/ipaddress.html#parsing-addresses-with-prefix-length.
   
   Separate point: pointing at latest is always tricky because that can change underneath you.  Better to point at a specific version or tag; that way the content stands a much better chance of remaining fixed. 



##########
manual/core/non_blocking/README.md:
##########
@@ -155,10 +155,17 @@ should not be used if strict lock-freedom is enforced.
 The `RateLimitingRequestThrottler` is currently blocking. The `ConcurrencyLimitingRequestThrottler`
 is lock-free.
 
-See the section about [throttling](../throttling) for details about these components. Depending on
+See the section about [throttling](../throttling/README.md) for details about these components. Depending on
 how many requests are being executed in parallel, the thread contention on these locks can be high:
 in short, if your application enforces strict lock-freedom, then you should not use the
 `RateLimitingRequestThrottler`.
+* `ConcurrencyLimitingRequestThrottler`
+* `RateLimitingRequestThrottler`
+
+See the section about [throttling](../throttling/README.md) for details about these components. Again, they 
+use locks internally, and depending on how many requests are being executed in parallel, the thread
+contention on these locks can be high: in short, if your application enforces strict lock-freedom, 
+then these components should not be used.

Review Comment:
   Looks like perhaps there was a missed deletion here; the content of the paragraph that's been added here is identical to the what's above and when I look at [this content on Github](https://github.com/SiyaoIsHiding/java-driver/tree/doc/manual/core/non_blocking) it reads oddly.



-- 
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: pr-unsubscribe@cassandra.apache.org

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


---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org