reduce amount of javadoc warnings (#560)

improve code quality by reducing amount of javadoc warnings

Author: TheSnoozer

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

@@ -19,31 +19,64 @@
 
 import java.util.Objects;
 
+/**
+ * A local git repository can either be "ahead", or "behind" in the number of commits
+ * relative to the remote repository. This class tracks the amount of commits the local git repository
+ * is "behind", or "ahead" relative to it's remote.
+ */
 public class AheadBehind {
 
+  /**
+   * Indication that we could not find a remote repository to calculate a "behind", or "ahead" relation.
+   */
   public static final AheadBehind NO_REMOTE = AheadBehind.of("NO_REMOTE", "NO_REMOTE");
 
   private final String ahead;
 
   private final String behind;
 
+  /**
+   * Constructor for a "AheadBehind"-object.
+   * @param ahead Number of commits the local repository is "ahead" in relation to it's remote.
+   * @param behind Number of commits the local repository is "behind" in relation to it's remote.
+   */
   private AheadBehind(String ahead, String behind) {
     this.ahead = ahead;
     this.behind = behind;
   }
 
+  /**
+   * Constructor for a "AheadBehind"-object.
+   * @param ahead Number of commits the local repository is "ahead" in relation to it's remote.
+   * @param behind Number of commits the local repository is "behind" in relation to it's remote.
+   *
+   * @return a "AheadBehind"-object.
+   */
   public static AheadBehind of(int ahead, int behind) {
     return new AheadBehind(String.valueOf(ahead), String.valueOf(behind));
   }
 
+  /**
+   * Constructor for a "AheadBehind"-object.
+   * @param ahead Number of commits the local repository is "ahead" in relation to it's remote.
+   * @param behind Number of commits the local repository is "behind" in relation to it's remote.
+   *
+   * @return a "AheadBehind"-object.
+   */
   public static AheadBehind of(String ahead, String behind) {
     return new AheadBehind(ahead, behind);
   }
 
+  /**
+   * @return Number of commits the local repository is "ahead" in relation to it's remote.
+   */
   public String ahead() {
     return ahead;
   }
 
+  /**
+   * @return Number of commits the local repository is "behind" in relation to it's remote.
+   */
   public String behind() {
     return behind;
   }

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

@@ -17,9 +17,20 @@
 
 package pl.project13.core;
 
+/**
+ * An exception to indicate that a required file could not be found.
+ */
 public class CannotReadFileException extends Exception {
   private static final long serialVersionUID = -9080356227094128542L;
 
+  /**
+   * Constructs a new exception with the specified cause
+   *
+   * @param  cause the cause (which is saved for later retrieval by the
+   *         {@link Exception#getCause()} method).  (A {@code null} value is
+   *         permitted, and indicates that the cause is nonexistent or
+   *         unknown.)
+   */
   public CannotReadFileException(Throwable cause) {
     super(cause);
   }

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

@@ -17,7 +17,17 @@
 
 package pl.project13.core;
 
+/**
+ * An enum to indicate how the {@code git.commit.id} property should be generated.
+ * See https://github.com/ktoso/maven-git-commit-id-plugin/issues/211 for further details.
+ */
 public enum CommitIdGenerationMode {
+  /**
+   * Indicator to generate a {@code git.commit.id.full} property
+   */
   FULL,
+  /**
+   * Indicator to generate a {@code git.commit.id} property (default)
+   */
   FLAT
 }

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

@@ -24,22 +24,63 @@
 public class GitCommitIdExecutionException extends Exception {
   private static final long serialVersionUID = 4608506012492555968L;
 
+  /**
+   * Constructs a new exception
+   */
   public GitCommitIdExecutionException() {
     super();
   }
 
+  /**
+   * Constructs a new exception with the specified detail message.
+   *
+   * @param message the detail message. The detail message is saved for
+   *          later retrieval by the {@link Exception#getMessage()} method.
+   */
   public GitCommitIdExecutionException(String message) {
     super(message);
   }
 
+  /**
+   * Constructs a new exception with the specified detail message and
+   * cause.
+   *
+   * @param  message the detail message (which is saved for later retrieval
+   *         by the {@link Exception#getMessage()} method).
+   * @param  cause the cause (which is saved for later retrieval by the
+   *         {@link Exception#getCause()} method).  (A {@code null} value is
+   *         permitted, and indicates that the cause is nonexistent or
+   *         unknown.)
+   */
   public GitCommitIdExecutionException(String message, Throwable cause) {
     super(message, cause);
   }
 
+  /**
+   * Constructs a new exception with the specified cause
+   *
+   * @param  cause the cause (which is saved for later retrieval by the
+   *         {@link Exception#getCause()} method).  (A {@code null} value is
+   *         permitted, and indicates that the cause is nonexistent or
+   *         unknown.)
+   */
   public GitCommitIdExecutionException(Throwable cause) {
     super(cause);
   }
 
+  /**
+   * Constructs a new exception with the specified detail message,
+   * cause, suppression enabled or disabled, and writable stack
+   * trace enabled or disabled.
+   *
+   * @param message the detail message.
+   * @param cause the cause.  (A {@code null} value is permitted,
+   * and indicates that the cause is nonexistent or unknown.)
+   * @param enableSuppression whether or not suppression is enabled
+   *                          or disabled
+   * @param writableStackTrace whether or not the stack trace should
+   *                           be writable
+   */
   public GitCommitIdExecutionException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
     super(message, cause, enableSuppression, writableStackTrace);
   }

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

@@ -17,36 +17,132 @@
 
 package pl.project13.core;
 
+/**
+ * A class that represents all properties that may be generated by the plugin and exposed to maven.
+ */
 public class GitCommitPropertyConstant {
-  // these properties will be exposed to maven
+  /**
+   * Represents the current branch name. Falls back to commit-id for detached HEAD.
+   */
   public static final String BRANCH = "branch";
+  /**
+   * Represents the count of commits that your local branch is ahead in perspective to the remote branch
+   * (usually the case when your local branch has committed changes that are not pushed yet to the remote branch).
+   */
   public static final String LOCAL_BRANCH_AHEAD = "local.branch.ahead";
+  /**
+   * Represents the count of commits that your local branch is behind in perspective to the remote branch
+   * (usually the case when there are commits in the remote branch that are not yet integrated into your local branch).
+   */
   public static final String LOCAL_BRANCH_BEHIND = "local.branch.behind";
+  /**
+   * A working tree is said to be "dirty" if it contains modifications
+   * which have not been committed to the current branch.
+   */
   public static final String DIRTY = "dirty";
-  // only one of the following two will be exposed, depending on the commitIdGenerationMode
+  /**
+   * Represents the commit’s SHA-1 hash. Note this is exchangeable with the git.commit.id.full property
+   * and might not be exposed. See {@code commitIdGenerationMode}.
+   */
   public static final String COMMIT_ID_FLAT = "commit.id";
+  /**
+   * Represents the commit’s SHA-1 hash. Note this is exchangeable with the git.commit.id property
+   * and might not be exposed. See {@code commitIdGenerationMode}.
+   */
   public static final String COMMIT_ID_FULL = "commit.id.full";
+  /**
+   * Represents the abbreviated (shorten version) commit hash.
+   */
   public static final String COMMIT_ID_ABBREV = "commit.id.abbrev";
+  /**
+   * Represents an object a human readable name based on a the commit (provides git describe for the given commit).
+   */
   public static final String COMMIT_DESCRIBE = "commit.id.describe";
+  /**
+   * Represents the same value as git.commit.id.describe,
+   * just with the git hash part removed (the g2414721 part from git describe).
+   */
   public static final String COMMIT_SHORT_DESCRIBE = "commit.id.describe-short";
+  /**
+   * Represents the git user name that is configured where the properties have been generated.
+   */
   public static final String BUILD_AUTHOR_NAME = "build.user.name";
+  /**
+   * Represents the git user eMail that is configured where the properties have been generated.
+   */
   public static final String BUILD_AUTHOR_EMAIL = "build.user.email";
+  /**
+   * Represents the (formatted) timestamp when the last build was executed.
+   * If written to the git.properties file represents the latest build time when that file was written / updated.
+   */
   public static final String BUILD_TIME = "build.time";
+  /**
+   * Represents the project version of the current maven project.
+   */
   public static final String BUILD_VERSION = "build.version";
+  /**
+   * Represents the hostname where the properties have been generated.
+   */
   public static final String BUILD_HOST = "build.host";
+  /**
+   * The git.build.number* variables are available on some hosted CIs and can be used to identify the
+   * "number" of the build. This represents a project specific build number.
+   */
   public static final String BUILD_NUMBER = "build.number";
+  /**
+   * The git.build.number* variables are available on some hosted CIs and can be used to identify the
+   * "number" of the build. This represents a system wide unique build number.
+   */
   public static final String BUILD_NUMBER_UNIQUE = "build.number.unique";
+  /**
+   * Represents the user name of the user who performed the commit.
+   */
   public static final String COMMIT_AUTHOR_NAME = "commit.user.name";
+  /**
+   * Represents the user eMail of the user who performed the commit.
+   */
   public static final String COMMIT_AUTHOR_EMAIL = "commit.user.email";
+  /**
+   * Represents the raw body (unwrapped subject and body) of the commit message.
+   */
   public static final String COMMIT_MESSAGE_FULL = "commit.message.full";
+  /**
+   * Represents the subject of the commit message - may not be suitable for filenames.
+   */
   public static final String COMMIT_MESSAGE_SHORT = "commit.message.short";
+  /**
+   * Represents the (formatted) time stamp when the commit has been performed.
+   */
   public static final String COMMIT_TIME = "commit.time";
+  /**
+   * Represents the (formatted) time stamp when the commit has been originally performed.
+   */
   public static final String COMMIT_AUTHOR_TIME = "commit.author.time";
+  /**
+   * Represents the (formatted) time stamp when the commit has been performed.
+   */
   public static final String COMMIT_COMMITTER_TIME = "commit.committer.time";
+  /**
+   * Represents the URL of the remote repository for the current git project.
+   */
   public static final String REMOTE_ORIGIN_URL = "remote.origin.url";
+  /**
+   * Represents a list of tags which contain the specified commit.
+   */
   public static final String TAGS = "tags";
+  /**
+   * Represents the name of the closest available tag.
+   * The closest tag may depend on your git describe config that may or may not take lightweight tags into consideration.
+   */
   public static final String CLOSEST_TAG_NAME = "closest.tag.name";
+  /**
+   * Represents the number of commits to the closest available tag.
+   * The closest tag may depend on your git describe config that may or may not take lightweight tags into consideration.
+   */
   public static final String CLOSEST_TAG_COMMIT_COUNT = "closest.tag.commit.count";
+  /**
+   * Represents the total count of all commits in the current repository.
+   */
   public static final String TOTAL_COMMIT_COUNT = "total.commit.count";
 
 }