[checkstyle] (javadoc) MissingJavadocMethod

apache · Mar 8, 2023 · 603efa9 · 603efa9
1 parent 4b6e465
commit 603efa9
Show file tree

Hide file tree

Showing 4 changed files with 119 additions and 3 deletions.
diff --git a/checkstyle-suppressions.xml b/checkstyle-suppressions.xml
@@ -25,6 +25,7 @@
   <suppress checks="MagicNumber" files=".*\/SlingOptions\.java"/>
   <suppress checks="MethodCount" files=".*\/SlingOptions\.java"/>
   <suppress checks="MethodLength" files=".*\/SlingVersionResolver\.java"/>
+  <suppress checks="MissingJavadocMethod" files=".*\/SlingOptions\.java"/>
   <suppress checks="MultipleStringLiterals" files=".*\/SlingOptions\.java"/>
   <suppress checks="MultipleStringLiterals" files=".*\/SlingVersionResolver\.java"/>
   <suppress checks="OverloadMethodsDeclarationOrder" files=".*\/SlingOptions\.java"/>

diff --git a/src/main/java/org/apache/sling/testing/paxexam/SlingVersionResolver.java b/src/main/java/org/apache/sling/testing/paxexam/SlingVersionResolver.java
@@ -34,6 +34,9 @@ public class SlingVersionResolver implements VersionResolver {
 
     private final Map<String, String> versions = new HashMap<>();
 
+    /**
+     * Creates a new {@code SlingVersionResolver}.
+     */
     public SlingVersionResolver() {
         versions.put("biz.aQute.bnd:biz.aQute.bndlib", "3.5.0");
         versions.put("biz.aQute.bnd:bndlib", "2.4.0");
@@ -297,20 +300,47 @@ private String key(final String groupId, final String artifactId) {
         return String.format("%s:%s", groupId, artifactId);
     }
 
+    /**
+     * Sets the version of the bundle.
+     *
+     * @param groupId    the group ID
+     * @param artifactId the artifact ID
+     * @param version    the version
+     * @return the previous version, or {@code null}
+     */
     public String setVersion(final String groupId, final String artifactId, final String version) {
         return versions.put(key(groupId, artifactId), version);
     }
 
+    /**
+     * Sets the version of the bundle by using the declared version from Maven project.
+     *
+     * @param groupId    the group ID
+     * @param artifactId the artifact ID
+     * @return the previous version, or {@code null}
+     */
     public String setVersionFromProject(final String groupId, final String artifactId) {
         final String version = MavenUtils.getArtifactVersion(groupId, artifactId);
         return versions.put(key(groupId, artifactId), version);
     }
 
+    /**
+     * Gets the version of the bundle.
+     *
+     * @param groupId    the group ID
+     * @param artifactId the artifact ID
+     * @return the version, or {@code null}
+     */
     @Override
     public String getVersion(final String groupId, final String artifactId) {
         return versions.get(key(groupId, artifactId));
     }
 
+    /**
+     * Gets the Java major version from System property {@code java.specification.version} or {@code 0} in case of error.
+     *
+     * @return the Java version
+     */
     public static int getJavaVersion() {
         final String version = System.getProperty("java.specification.version");
         try {

diff --git a/src/main/java/org/apache/sling/testing/paxexam/TestSupport.java b/src/main/java/org/apache/sling/testing/paxexam/TestSupport.java
@@ -62,23 +62,43 @@ public abstract class TestSupport {
 
     private final String workingDirectory = String.format("%s/target/paxexam/%s/%s", PathUtils.getBaseDir(), getClass().getSimpleName(), UUID.randomUUID());
 
+    /**
+     * Provides a random path for a working directory below Maven's build target directory.
+     *
+     * @return the absolute path for working directory
+     */
     protected String workingDirectory() {
         return workingDirectory;
     }
 
+    /**
+     * Provides Felix HTTP Service's HTTP port ({@code org.osgi.service.http.port}).
+     *
+     * @return the HTTP port
+     * @throws IOException if reading OSGi configuration fails
+     */
     protected int httpPort() throws IOException {
         final Dictionary<String, Object> properties = configurationAdmin.getConfiguration("org.apache.felix.http").getProperties();
         return Integer.parseInt(properties.get("org.osgi.service.http.port").toString());
     }
 
+    /**
+     * Provides the Jacoco VM option when System property {@code jacoco.command} is set.
+     *
+     * @return the property option
+     */
     protected OptionalCompositeOption jacoco() {
         final String jacocoCommand = System.getProperty("jacoco.command");
         @SuppressWarnings("checkstyle:AvoidInlineConditionals")
         final VMOption option = Objects.nonNull(jacocoCommand) && !jacocoCommand.trim().isEmpty() ? vmOption(jacocoCommand) : null;
         return when(Objects.nonNull(option)).useOptions(option);
     }
 
-    // commons options for both default and server mode
+    /**
+     * Provides commons property and provisioning options for both default and server mode.
+     *
+     * @return the composite option
+     */
     protected ModifiableCompositeOption commonConfiguration() {
         return composite(
             failOnUnresolvedBundles(),
@@ -94,7 +114,11 @@ protected ModifiableCompositeOption commonConfiguration() {
         );
     }
 
-    // default mode
+    /**
+     * Provides base property and provisioning options for default mode.
+     *
+     * @return the composite option
+     */
     protected ModifiableCompositeOption baseConfiguration() {
         return composite(
             commonConfiguration(),
@@ -104,11 +128,20 @@ protected ModifiableCompositeOption baseConfiguration() {
         );
     }
 
-    // server mode
+    /**
+     * Provides base property and provisioning options for server mode.
+     *
+     * @return the composite option
+     */
     protected ModifiableCompositeOption serverBaseConfiguration() {
         return commonConfiguration();
     }
 
+    /**
+     * Finds a free local port.
+     *
+     * @return the free local port
+     */
     @SuppressWarnings("checkstyle:IllegalCatch")
     public static int findFreePort() {
         try (ServerSocket serverSocket = new ServerSocket(0)) {
@@ -118,23 +151,45 @@ public static int findFreePort() {
         }
     }
 
+    /**
+     * Provides an option to set the System property {@code pax.exam.osgi.unresolved.fail} to {@code "true"}.
+     *
+     * @return the property option
+     */
     public static Option failOnUnresolvedBundles() {
         return systemProperty("pax.exam.osgi.unresolved.fail").value("true");
     }
 
+    /**
+     * Reads the System property {@code maven.repo.local} and provides an option to set the System property {@code org.ops4j.pax.url.mvn.localRepository} when former is not empty.
+     *
+     * @return the property option
+     */
     public static Option localMavenRepo() {
         final String localRepository = System.getProperty("maven.repo.local", ""); // PAXEXAM-543
         return when(localRepository.length() > 0).useOptions(
             systemProperty("org.ops4j.pax.url.mvn.localRepository").value(localRepository)
         );
     }
 
+    /**
+     * Reads the pathname of the test bundle from the given System property and provides a provisioning option.
+     *
+     * @param systemProperty the System property which contains the pathname of the test bundle
+     * @return the provisioning option
+     */
     public static Option testBundle(final String systemProperty) {
         final String filename = System.getProperty(systemProperty);
         final File file = new File(filename);
         return bundle(file.toURI().toString());
     }
 
+    /**
+     * Builds an OSGi bundle with BND from given classes and provides it as provisioning option.
+     *
+     * @param classes the classes to include in the OSGi bundle
+     * @return the provisioning option
+     */
     public static Option buildBundleWithBnd(final Class... classes) {
         final TinyBundle bundle = org.ops4j.pax.tinybundles.core.TinyBundles.bundle();
         for (final Class clazz : classes) {

diff --git a/src/main/resources/templates/SlingVersionResolver.hbs b/src/main/resources/templates/SlingVersionResolver.hbs
@@ -34,6 +34,9 @@ public class SlingVersionResolver implements VersionResolver {
 
     private final Map<String, String> versions = new HashMap<>();
 
+    /**
+     * Creates a new {@code SlingVersionResolver}.
+     */
     public SlingVersionResolver() {
         versions.put("biz.aQute.bnd:biz.aQute.bndlib", "3.5.0");
         versions.put("biz.aQute.bnd:bndlib", "2.4.0");
@@ -115,20 +118,47 @@ public class SlingVersionResolver implements VersionResolver {
         return String.format("%s:%s", groupId, artifactId);
     }
 
+    /**
+     * Sets the version of the bundle.
+     *
+     * @param groupId    the group ID
+     * @param artifactId the artifact ID
+     * @param version    the version
+     * @return the previous version, or {@code null}
+     */
     public String setVersion(final String groupId, final String artifactId, final String version) {
         return versions.put(key(groupId, artifactId), version);
     }
 
+    /**
+     * Sets the version of the bundle by using the declared version from Maven project.
+     *
+     * @param groupId    the group ID
+     * @param artifactId the artifact ID
+     * @return the previous version, or {@code null}
+     */
     public String setVersionFromProject(final String groupId, final String artifactId) {
         final String version = MavenUtils.getArtifactVersion(groupId, artifactId);
         return versions.put(key(groupId, artifactId), version);
     }
 
+    /**
+     * Gets the version of the bundle.
+     *
+     * @param groupId    the group ID
+     * @param artifactId the artifact ID
+     * @return the version, or {@code null}
+     */
     @Override
     public String getVersion(final String groupId, final String artifactId) {
         return versions.get(key(groupId, artifactId));
     }
 
+    /**
+     * Gets the Java major version from System property {@code java.specification.version} or {@code 0} in case of error.
+     *
+     * @return the Java version
+     */
     public static int getJavaVersion() {
         final String version = System.getProperty("java.specification.version");
         try {