Merge pull request #527 from TheSnoozer/fix-javadoc

fix javadoc generation for java 12 / 13

core/pom.xml

@@ -21,6 +21,21 @@
         <junit.version>4.13.1</junit.version>
     </properties>
 
+    <build>
+        <plugins>
+            <!-- Setting built-in java compiler properties -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>${java.target}</source>
+                    <target>${java.target}</target>
+                    <compilerArgument>-Xlint:deprecation</compilerArgument>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
     <dependencies>
         <!-- JGit -->
         <dependency>

core/src/main/java/pl/project13/core/GitDataProvider.java

@@ -221,6 +221,7 @@ void validateAbbrevLength(int abbrevLength) throws GitCommitIdExecutionException
    *
    * @param env environment settings
    * @return results of getBranchName() or, if in Jenkins/Hudson, value of GIT_BRANCH
+   * @throws GitCommitIdExecutionException the branch name could not be determined
    */
   protected String determineBranchName(@Nonnull Map<String, String> env) throws GitCommitIdExecutionException {
     BuildServerDataProvider buildServerDataProvider = BuildServerDataProvider.getBuildServerProvider(env,log);

core/src/main/java/pl/project13/core/NativeGitProvider.java

@@ -371,10 +371,24 @@ private ProcessRunner getRunner() {
   }
 
   public interface ProcessRunner {
-    /** Run a command and return the entire output as a String - naive, we know. */
+    /** Run a command and return the entire output as a String - naive, we know.
+     *
+     * @param directory the directory where the command should be executed in
+     * @param nativeGitTimeoutInMs the timeout in milliseconds before the command get's terminated
+     * @param command the command to execute
+     * @return the output obtained from stdout by running the command
+     * @throws IOException the command execution failed
+     */
     String run(File directory, long nativeGitTimeoutInMs, String command) throws IOException;
 
-    /** Run a command and return false if it contains at least one output line*/
+    /** Run a command and return false if it contains at least one output line
+     *
+     * @param directory the directory where the command should be executed in
+     * @param nativeGitTimeoutInMs the timeout in milliseconds before the command get's terminated
+     * @param command the command to execute
+     * @return false if the output of the command contains at least one line on stdout, true otherwise
+     * @throws IOException the command execution failed
+     */
     boolean runEmpty(File directory, long nativeGitTimeoutInMs, String command) throws IOException;
   }
 

core/src/main/java/pl/project13/core/cibuild/AwsCodeBuildBuildServerData.java

@@ -31,6 +31,8 @@ public class AwsCodeBuildBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the AWS specific environment variable; false otherwise
    * @see <a href="https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html">Environment variables in build environments</a>
    */
   public static boolean isActiveServer(Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/AzureDevOpsBuildServerData.java

@@ -31,6 +31,8 @@ public class AzureDevOpsBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Azure specific environment variable; false otherwise
    * @see <a href="https://docs.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#build-variables">Azure DevOps - Build variables</a>
    */
   public static boolean isActiveServer(@Nonnull Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/BambooBuildServerData.java

@@ -29,6 +29,11 @@ public class BambooBuildServerData extends BuildServerDataProvider {
     super(log, env);
   }
 
+  /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Bamboo specific environment variable; false otherwise
+   * @see <a href="https://confluence.atlassian.com/bamboo/bamboo-variables-289277087.html#Bamboovariables-Build-specificvariables">Bamboo Variables</a>
+   */
   public static boolean isActiveServer(Map<String, String> env) {
     return env.containsKey("bamboo_buildKey") ||
             env.containsKey("bamboo.buildKey") ||

core/src/main/java/pl/project13/core/cibuild/CircleCiBuildServerData.java

@@ -31,6 +31,8 @@ public class CircleCiBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Circle CI specific environment variable; false otherwise
    * @see <a href="https://circleci.com/docs/2.0/env-vars/#built-in-environment-variables">CircleCIBuiltInVariables</a>
    */
   public static boolean isActiveServer(Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/GitHubBuildServerData.java

@@ -33,6 +33,8 @@ public class GitHubBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Github specific environment variable; false otherwise
    * @see <a href="https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables">GitHubActionsUsingEnvironmentVariables</a>
    */
   public static boolean isActiveServer(Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/GitlabBuildServerData.java

@@ -31,6 +31,8 @@ public class GitlabBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Gitlab specific environment variable; false otherwise
    * @see <a href="https://docs.gitlab.com/ce/ci/variables/predefined_variables.html">GitlabCIVariables</a>
    */
   public static boolean isActiveServer(Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/HudsonJenkinsBuildServerData.java

@@ -31,6 +31,8 @@ public class HudsonJenkinsBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Hudson/Jenkins specific environment variable; false otherwise
    * @see <a href="https://wiki.jenkins-ci.org/display/JENKINS/Building+a+software+project#Buildingasoftwareproject-JenkinsSetEnvironmentVariables">JenkinsSetEnvironmentVariables</a>
    */
   public static boolean isActiveServer(@Nonnull Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/TeamCityBuildServerData.java

@@ -43,6 +43,8 @@ public class TeamCityBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the TeamCity specific environment variable; false otherwise
    * @see <a href=https://confluence.jetbrains.com/display/TCD18/Predefined+Build+Parameters#PredefinedBuildParameters-ServerBuildProperties>TeamCity</a>
    */
   public static boolean isActiveServer(@Nonnull Map<String, String> env) {

core/src/main/java/pl/project13/core/cibuild/TravisBuildServerData.java

@@ -31,6 +31,8 @@ public class TravisBuildServerData extends BuildServerDataProvider {
   }
 
   /**
+   * @param env The current system environment variables, obtained via System.getenv().
+   * @return true, if the system environment variables contain the Travis specific environment variable; false otherwise
    * @see <a href=https://docs.travis-ci.com/user/environment-variables/#Default-Environment-Variables>Travis</a>
    */
   public static boolean isActiveServer(@Nonnull Map<String, String> env) {

core/src/main/java/pl/project13/core/jgit/DescribeCommand.java

@@ -76,8 +76,10 @@ public class DescribeCommand extends GitCommand<DescribeResult> {
   /**
    * Creates a new describe command which interacts with a single repository
    *
+   * @param evaluateOnCommit the commit that should be used as reference to generate the properties from
    * @param repo the {@link Repository} this command should interact with
    * @param log logger bridge to direct logs to
+   * @return itself with the options set as specified by the arguments to allow fluent configuration
    */
   @Nonnull
   public static DescribeCommand on(String evaluateOnCommit, Repository repo, LoggerBridge log) {
@@ -87,7 +89,10 @@ public static DescribeCommand on(String evaluateOnCommit, Repository repo, Logge
   /**
    * Creates a new describe command which interacts with a single repository
    *
-   * @param repo the {@link org.eclipse.jgit.lib.Repository} this command should interact with
+   * @param evaluateOnCommit the commit that should be used as reference to generate the properties from
+   * @param repo the {@link Repository} this command should interact with
+   * @param log logger bridge to direct logs to
+   * @return itself with the options set as specified by the arguments to allow fluent configuration
    */
   private DescribeCommand(@Nonnull String evaluateOnCommit, @Nonnull Repository repo, @Nonnull LoggerBridge log) {
     super(repo);
@@ -102,6 +107,9 @@ private DescribeCommand(@Nonnull String evaluateOnCommit, @Nonnull Repository re
    * Show uniquely abbreviated commit object as fallback.
    *
    * <pre>true</pre> by default.
+   *
+   * @param always set to `true` when you want the describe command show uniquely abbreviated commit object as fallback.
+   * @return itself with the `--always` option set as specified by the argument to allow fluent configuration
    */
   @Nonnull
   public DescribeCommand always(boolean always) {
@@ -120,6 +128,9 @@ public DescribeCommand always(boolean always) {
    * since tag v1.2 that points at object deadbee....).
    *
    * <pre>false</pre> by default.
+   *
+   * @param forceLongFormat set to `true` if you always want to output the long format
+   * @return itself with the `--long` option set as specified by the argument to allow fluent configuration
    */
   @Nonnull
   public DescribeCommand forceLongFormat(@Nullable Boolean forceLongFormat) {
@@ -137,6 +148,9 @@ public DescribeCommand forceLongFormat(@Nullable Boolean forceLongFormat) {
    * use <b>N</b> digits, or as many digits as needed to form a unique object name.
    *
    * An `n` of 0 will suppress long format, only showing the closest tag.
+   *
+   * @param n the length of the abbreviated object name
+   * @return itself with the `--abbrev` option set as specified by the argument to allow fluent configuration
    */
   @Nonnull
   public DescribeCommand abbrev(@Nullable Integer n) {
@@ -180,6 +194,9 @@ public DescribeCommand abbrev(@Nullable Integer n) {
    * things like "i'll get back to that" etc - you don't need such tags to be exposed. But if you want lightweight
    * tags to be included in the search, enable this option.
    * </p>
+   *
+   * @param includeLightweightTagsInSearch set to `true` if you want to matching a lightweight (non-annotated) tag
+   * @return itself with the `--tags` option set as specified by the argument to allow fluent configuration
    */
   @Nonnull
   public DescribeCommand tags(@Nullable Boolean includeLightweightTagsInSearch) {
@@ -192,6 +209,7 @@ public DescribeCommand tags(@Nullable Boolean includeLightweightTagsInSearch) {
 
   /**
    * Alias for {@link DescribeCommand#tags(Boolean)} with <b>true</b> value
+   * @return itself with the `--tags` option set to `true` to allow fluent configuration
    */
   public DescribeCommand tags() {
     return tags(true);
@@ -201,6 +219,7 @@ public DescribeCommand tags() {
    * Apply all configuration options passed in with `config`.
    * If a setting is null, it will not be applied - so for abbrev for example, the default 7 would be used.
    *
+   * @param config A configuration that shall be applied to the current one
    * @return itself, after applying the settings
    */
   @Nonnull
@@ -222,7 +241,7 @@ public DescribeCommand apply(@Nullable GitDescribeConfig config) {
    * working tree is dirty.
    *
    * @param dirtyMarker the marker name to be appended to the describe output when the workspace is dirty
-   * @return itself, to allow fluent configuration
+   * @return itself with the `--dirty` option set as specified by the argument to allow fluent configuration
    */
   @Nonnull
   public DescribeCommand dirty(@Nullable String dirtyMarker) {
@@ -237,7 +256,7 @@ public DescribeCommand dirty(@Nullable String dirtyMarker) {
    * Consider only those tags which match the given glob pattern.
    *
    * @param pattern the glob style pattern to match against the tag names
-   * @return itself, to allow fluent configuration
+   * @return itself with the `--match` option set as specified by the argument to allow fluent configuration
    */
   @Nonnull
   public DescribeCommand match(@Nullable String pattern) {
@@ -306,6 +325,12 @@ public DescribeResult call() throws GitAPIException {
    * and will fallback to a plain commit hash if nothing better is returnable.
    *
    * The exact logic is following what <pre>git-describe</pre> would do.
+   *
+   * @param objectReader A reader to read objects from {@link Repository#getObjectDatabase()}.
+   * @param headCommitId An unique hash of the head-commit
+   * @param dirty An indication if the current repository is considered <pre>dirty</pre>
+   * @param howFarFromWhichTag A Pair that consists of a string and an integer. The String represents the closest Tag and the integer the amount of commits that have been preformed since then
+   * @return The result of a <code>git describe</code> command with the specified settings.
    */
   private DescribeResult createDescribeResult(ObjectReader objectReader, ObjectId headCommitId, boolean dirty, @Nullable Pair<Integer, String> howFarFromWhichTag) {
     if (howFarFromWhichTag == null) {

core/src/main/java/pl/project13/core/jgit/DescribeResult.java

@@ -175,6 +175,8 @@ public String dirtyMarker() {
    * a longer one will be used (which WILL guarantee uniqueness).
    * If you need the full commit id, it's always available via {@link DescribeResult#commitObjectId()}.
    * </p>
+   *
+   * @return The (possibly) "g" prefixed <strong>abbreviated</strong> object id of a commit.
    */
   @Nullable
   public String prefixedCommitId() {

core/src/main/java/pl/project13/core/jgit/JGitCommon.java

@@ -264,7 +264,9 @@ public List<RevCommit> findCommitsUntilSomeTag(Repository repo, RevCommit head,
 
   /**
    * Calculates the distance (number of commits) between the given parent and child commits.
-   *
+   * @param repo the {@link Repository} this command should interact with
+   * @param child the child commit (starting point)
+   * @param parent the parent commit (end point)
    * @return distance (number of commits) between the given commits
    * @see <a href="https://github.com/mdonoughe/jgit-describe/blob/master/src/org/mdonoughe/JGitDescribeTask.java">mdonoughe/jgit-describe/blob/master/src/org/mdonoughe/JGitDescribeTask.java</a>
    */

pom.xml

@@ -144,6 +144,13 @@
                     <compilerArgument>-Xlint:deprecation</compilerArgument>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <configuration>
+                    <source>8</source>
+                </configuration>
+            </plugin>
         </plugins>
     </build>