JENKINS-49202: Add getComment() to ChangeLogSet.Entry with tests

Author: 0xShubhamSolanki

core/src/main/java/hudson/scm/ChangeLogSet.java

@@ -47,8 +47,7 @@
  * For the change list at project level, see {@link SCM}.
  *
  * <p>
- * {@link Iterator} is expected to return newer changes first then older changes
- * later.
+ * {@link Iterator} is expected to return newer changes first then older changes later.
  *
  * @author Kohsuke Kawaguchi
  */
@@ -117,7 +116,6 @@ public final Object[] getItems() {
 
     /**
      * Optional identification of the kind of SCM being used.
-     *
      * @return a short token, such as the SCM's main CLI executable name
      * @since 1.284
      */
@@ -128,7 +126,6 @@ public String getKind() {
 
     /**
      * Constant instance that represents no changes.
-     *
      * @since 1.568
      */
     public static ChangeLogSet<? extends ChangeLogSet.Entry> createEmpty(Run build) {
@@ -156,8 +153,16 @@ protected void setParent(ChangeLogSet parent) {
         }
 
         /**
-         * Returns a human readable display name of the commit number, revision number,
-         * etc.
+         * Returns a human readable display name of the commit number, revision number, and such thing
+         * that identifies this entry.
+         *
+         * <p>
+         * This method is primarily intended for visualization of the data.
+         *
+         * @return
+         *      null if such a concept doesn't make sense for the implementation. For example,
+         *      in CVS there's no single identifier for commits. Each file gets a different revision number.
+         * @since 1.405
          */
         @Exported
         public String getCommitId() {
@@ -166,26 +171,38 @@ public String getCommitId() {
 
         /**
          * Returns the timestamp of this commit in the {@link Date#getTime()} format.
+         *
+         * <p>
+         * This method is primarily intended for visualization of the data.
+         *
+         * @return
+         *      -1 if the implementation doesn't support it (for example, in CVS a commit
+         *      spreads over time between multiple changes on multiple files, so there's no single timestamp.)
+         * @since 1.405
          */
         @Exported
         public long getTimestamp() {
             return -1;
         }
 
         /**
-         * Gets the first line commit message (short message).
+         * Gets the "commit message".
+         *
+         * <p>
+         * The exact definition depends on the individual SCM implementation.
+         *
+         * @return
+         *      Can be empty but never null.
          */
         @Exported
         public abstract String getMsg();
 
-        /**
-         * Returns the full commit message.
+        /** Returns the full commit message.
          *
-         * Default implementation returns the same value as getMsg().
-         * SCM implementations can override this if they support full message
-         * separately.
+         * Default implementation returns the same value as {@link #getMsg()}.
+         * SCM implementations may override if they provide a separate full message.
          *
-         * @since TODO
+         * @since 2.552
          */
         @Exported
         public String getComment() {
@@ -194,26 +211,46 @@ public String getComment() {
 
         /**
          * The user who made this change.
+         *
+         * @return
+         *      never null.
          */
         @Exported
         public abstract User getAuthor();
 
         /**
-         * Returns affected paths.
+         * Returns a set of paths in the workspace that was
+         * affected by this change.
+         *
+         * <p>
+         * Contains string like 'foo/bar/zot'. No leading/trailing '/',
+         * and separator must be normalized to '/'.
+         *
+         * @return never null.
          */
         @Exported
         public abstract Collection<String> getAffectedPaths();
 
         /**
-         * Returns affected files.
+         * Returns a set of paths in the workspace that was
+         * affected by this change.
+         * <p>
+         * Noted: since this is a new interface, some of the SCMs may not have
+         * implemented this interface. The default implementation for this
+         * interface is throw UnsupportedOperationException
+         * <p>
+         * It doesn't throw NoSuchMethodException because I rather to throw a
+         * runtime exception
+         *
+         * @return AffectedFile never null.
+         * @since 1.309
          */
         public Collection<? extends AffectedFile> getAffectedFiles() {
             String scm = "this SCM";
             ChangeLogSet parent = getParent();
             if (null != parent) {
                 String kind = parent.getKind();
-                if (null != kind && !kind.trim().isEmpty())
-                    scm = kind;
+                if (null != kind && !kind.trim().isEmpty()) scm = kind;
             }
             throw new UnsupportedOperationException("getAffectedFiles() is not implemented by " + scm);
         }
@@ -227,11 +264,9 @@ public String getMsgAnnotated() {
                 try {
                     a.annotate(parent.run, this, markup);
                 } catch (RuntimeException e) {
-                    LOGGER.info("ChangeLogAnnotator " + a.toString() + " failed to annotate message '" + getMsg()
-                            + "'; " + e.getMessage());
+                    LOGGER.info("ChangeLogAnnotator " + a.toString() + " failed to annotate message '" + getMsg() + "'; " + e.getMessage());
                 } catch (Error e) {
-                    LOGGER.severe("ChangeLogAnnotator " + a + " failed to annotate message '" + getMsg() + "'; "
-                            + e.getMessage());
+                    LOGGER.severe("ChangeLogAnnotator " + a + " failed to annotate message '" + getMsg() + "'; " + e.getMessage());
                 }
 
             return markup.toString(false);
@@ -266,6 +301,7 @@ public interface AffectedFile {
          */
         String getPath();
 
+
         /**
          * Return whether the file is new/modified/deleted
          */

core/src/test/java/hudson/scm/ChangeLogSetEntryTest.java

@@ -0,0 +1,62 @@
+package hudson.scm;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import hudson.model.User;
+import java.util.Collection;
+import java.util.Collections;
+import org.junit.jupiter.api.Test;
+
+public class ChangeLogSetEntryTest {
+
+    @Test
+    public void getCommentDefaultsToMsg() {
+        ChangeLogSet.Entry entry = new ChangeLogSet.Entry() {
+
+            @Override
+            public String getMsg() {
+                return "short message";
+            }
+
+            @Override
+            public User getAuthor() {
+                return null;
+            }
+
+            @Override
+            public Collection<String> getAffectedPaths() {
+                return Collections.emptyList();
+            }
+        };
+
+        assertEquals("short message", entry.getComment());
+    }
+
+    @Test
+    public void getCommentCanBeOverridden() {
+        ChangeLogSet.Entry entry = new ChangeLogSet.Entry() {
+
+            @Override
+            public String getMsg() {
+                return "short";
+            }
+
+            @Override
+            public String getComment() {
+                return "full commit message";
+            }
+
+            @Override
+            public User getAuthor() {
+                return null;
+            }
+
+            @Override
+            public Collection<String> getAffectedPaths() {
+                return Collections.emptyList();
+            }
+        };
+
+        assertEquals("full commit message", entry.getComment());
+    }
+}