[doc] resolve a bunch of javadoc lint warnings

kares · kares · commit 7e6e1650be52 · 2025-05-30T14:30:11.000+02:00
diff --git a/pom.xml b/pom.xml
@@ -336,15 +336,26 @@
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-javadoc-plugin</artifactId>
             <version>3.11.2</version>
+            <configuration>
+              <tags>
+                <tag>
+                  <name>apiNote</name>
+                  <placement>a</placement>
+                  <head>API:</head>
+                </tag>
+                <tag>
+                  <name>implNote</name>
+                  <placement>a</placement>
+                  <head>NOTE:</head>
+                </tag>
+              </tags>
+            </configuration>
             <executions>
               <execution>
                 <id>attach-javadocs</id>
                 <goals>
                   <goal>jar</goal>
                 </goals>
-                <configuration>
-                  <additionalparam>${javadoc.opts}</additionalparam>
-                </configuration>
               </execution>
             </executions>
           </plugin>
@@ -365,15 +376,6 @@
         </plugins>
       </build>
     </profile>
-    <profile>
-      <id>java8-disable-doclint</id>
-      <activation>
-        <jdk>[1.8,)</jdk>
-      </activation>
-      <properties>
-        <javadoc.opts>-Xdoclint:none</javadoc.opts>
-      </properties>
-    </profile>
   </profiles>
 
 </project>
diff --git a/src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java b/src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java
@@ -76,7 +76,7 @@ public void setRackupScript(String rackupScript) {
     /**
      * Initialize this factory using the given context.
      *
-     * NOTE: exception handling is left to the outer factory.
+     * @implNote exception handling is left to the outer factory.
      * @param rackContext the RackContext
      */
     @Override
@@ -94,7 +94,7 @@ public void init(final RackContext rackContext) {
     /**
      * Creates a new application instance (without initializing it).
      *
-     * NOTE: exception handling is left to the outer factory.
+     * @implNote exception handling is left to the outer factory.
      * @return new application instance
      */
     @Override
@@ -109,7 +109,7 @@ public IRubyObject create(Ruby runtime) {
     /**
      * Creates a new application and initializes it.
      *
-     * NOTE: exception handling is left to the outer factory.
+     * @implNote exception handling is left to the outer factory.
      * @return new, initialized application
      */
     @Override
@@ -122,7 +122,7 @@ public RackApplication getApplication() {
     /**
      * Destroys the application (assumably) created by this factory.
      *
-     * NOTE: exception handling is left to the outer factory.
+     * @implNote exception handling is left to the outer factory.
      * @param app the application to "release"
      */
     @Override
@@ -352,9 +352,9 @@ protected void loadJRubyRack(final Ruby runtime) {
     /**
      * Initializes the runtime (exports the context, boots the Rack handler).
      *
-     * NOTE: visible due to specs
+     * @apiNote Internal API, only visible due tests.
      *
-     * @param runtime
+     * @param runtime the JRuby runtime
      */
     public void initRuntime(final Ruby runtime) {
         loadJRubyRack(runtime);
@@ -399,11 +399,11 @@ public void initRuntime(final Ruby runtime) {
     /**
      * Checks and sets the required Rack version (if specified as a magic comment).
      *
-     * e.g. # rack.version: ~>1.3.6
+     * e.g. # rack.version: =1.3.6
      *
-     * NOTE: (package) visible due specs
+     * @apiNote Internal API, only visible due tests.
      *
-     * @param runtime
+     * @param runtime the JRuby runtime
      * @return the rack version requirement
      */
     public String checkAndSetRackVersion(final Ruby runtime) {
diff --git a/src/main/java/org/jruby/rack/RackConfig.java b/src/main/java/org/jruby/rack/RackConfig.java
@@ -80,8 +80,7 @@ public interface RackConfig {
      * By returning null the environment (JRuby sets up System.getenv) will be
      * kept as is. 
      *
-     * NOTE: This method if not returning null should return a mutable map.
-     *
+     * @apiNote This method if not returning null should return a mutable map.
      * @return the <code>ENV</code> to be used in started Ruby runtimes
      */
     Map<String, String> getRuntimeEnvironment();
