Documentation. Added JavaDoc comments.

diff --git a/src/com/gitblit/models/AnnotatedLine.java b/src/com/gitblit/models/AnnotatedLine.java
index 3d124765206f68b32e433eabb4730c6e27ead869..69b55bcdc9db77d8d742a862e5fbaa7d6895ac3f 100644 (file)
--- a/src/com/gitblit/models/AnnotatedLine.java
+++ b/src/com/gitblit/models/AnnotatedLine.java
@@ -20,6 +20,13 @@ import java.util.Date;
 \r
 import org.eclipse.jgit.revwalk.RevCommit;\r
 \r
+/**\r
+ * AnnotatedLine is a serializable model class that represents a the most recent\r
+ * author, date, and commit id of a line in a source file.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class AnnotatedLine implements Serializable {\r
 \r
        private static final long serialVersionUID = 1L;\r

diff --git a/src/com/gitblit/models/GitNote.java b/src/com/gitblit/models/GitNote.java
index 3b66d89f176c8fc5031de9b489a269a3b600abcf..c333a8811849215caa957899060ad584e4936698 100644 (file)
--- a/src/com/gitblit/models/GitNote.java
+++ b/src/com/gitblit/models/GitNote.java
@@ -17,12 +17,20 @@ package com.gitblit.models;
 \r
 import java.io.Serializable;\r
 \r
+/**\r
+ * GitNote is a serializable model class that represents a git note. This class\r
+ * retains an instance of the RefModel which contains the commit in which this\r
+ * git note was created.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class GitNote implements Serializable {\r
 \r
        private static final long serialVersionUID = 1L;\r
 \r
-       public String content;\r
-       public RefModel notesRef;\r
+       public final String content;\r
+       public final RefModel notesRef;\r
 \r
        public GitNote(RefModel notesRef, String text) {\r
                this.notesRef = notesRef;\r

diff --git a/src/com/gitblit/models/Metric.java b/src/com/gitblit/models/Metric.java
index 9ff270ade89386f5198b0a24a498087457953795..e7c49a45a6cf0c5f2a88dd4cbbab397e574d819d 100644 (file)
--- a/src/com/gitblit/models/Metric.java
+++ b/src/com/gitblit/models/Metric.java
@@ -17,11 +17,18 @@ package com.gitblit.models;
 \r
 import java.io.Serializable;\r
 \r
+/**\r
+ * Metric is a serializable model class that encapsulates metrics for some given\r
+ * type.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class Metric implements Serializable {\r
 \r
        private static final long serialVersionUID = 1L;\r
 \r
-       public String name;\r
+       public final String name;\r
        public double count;\r
        public double tag;\r
        public int duration;\r

diff --git a/src/com/gitblit/models/PathModel.java b/src/com/gitblit/models/PathModel.java
index 0841531783af5736679d0dd68b98f5f343857fdd..c78b300c08f04bc75587efb04b605d53cfd6e2d3 100644 (file)
--- a/src/com/gitblit/models/PathModel.java
+++ b/src/com/gitblit/models/PathModel.java
@@ -20,6 +20,13 @@ import java.io.Serializable;
 import org.eclipse.jgit.diff.DiffEntry.ChangeType;\r
 import org.eclipse.jgit.lib.FileMode;\r
 \r
+/**\r
+ * PathModel is a serializable model class that represents a file or a folder,\r
+ * including all its metadata and associated commit id.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class PathModel implements Serializable, Comparable<PathModel> {\r
 \r
        private static final long serialVersionUID = 1L;\r
@@ -71,6 +78,13 @@ public class PathModel implements Serializable, Comparable<PathModel> {
                return 1;\r
        }\r
 \r
+       /**\r
+        * PathChangeModel is a serializable class that represents a file changed in\r
+        * a commit.\r
+        * \r
+        * @author James Moger\r
+        * \r
+        */\r
        public static class PathChangeModel extends PathModel {\r
 \r
                private static final long serialVersionUID = 1L;\r

diff --git a/src/com/gitblit/models/RefModel.java b/src/com/gitblit/models/RefModel.java
index 92c394c19dc24b80c883af99249a7319b102261e..fab5fc1f5a71deff8ca6dd666aa9ed39513422a8 100644 (file)
--- a/src/com/gitblit/models/RefModel.java
+++ b/src/com/gitblit/models/RefModel.java
@@ -25,6 +25,13 @@ import org.eclipse.jgit.revwalk.RevCommit;
 import org.eclipse.jgit.revwalk.RevObject;\r
 import org.eclipse.jgit.revwalk.RevTag;\r
 \r
+/**\r
+ * RefModel is a serializable model class that represents a tag or branch and\r
+ * includes the referenced object.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class RefModel implements Serializable, Comparable<RefModel> {\r
 \r
        private static final long serialVersionUID = 1L;\r

diff --git a/src/com/gitblit/models/RepositoryModel.java b/src/com/gitblit/models/RepositoryModel.java
index 97ae5184701b57086075e66430e1b06a93f3b076..386373789ed28f48f9c108989b2e2436d633df00 100644 (file)
--- a/src/com/gitblit/models/RepositoryModel.java
+++ b/src/com/gitblit/models/RepositoryModel.java
@@ -20,6 +20,13 @@ import java.util.Date;
 \r
 import com.gitblit.Constants.AccessRestrictionType;\r
 \r
+/**\r
+ * RepositoryModel is a serializable model class that represents a Gitblit\r
+ * repository including its configuration settings and access restriction.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class RepositoryModel implements Serializable {\r
 \r
        private static final long serialVersionUID = 1L;\r

diff --git a/src/com/gitblit/models/TicketModel.java b/src/com/gitblit/models/TicketModel.java
index d86a073da77fd2db3c4806b5937d87aaa23fa7be..b8043c6c4faf44bb431b97c58124bcc92e2a5e18 100644 (file)
--- a/src/com/gitblit/models/TicketModel.java
+++ b/src/com/gitblit/models/TicketModel.java
@@ -21,6 +21,12 @@ import java.util.ArrayList;
 import java.util.Date;\r
 import java.util.List;\r
 \r
+/**\r
+ * TicketModel is a serializable model class that represents a Ticgit ticket.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class TicketModel implements Serializable, Comparable<TicketModel> {\r
 \r
        private static final long serialVersionUID = 1L;\r
@@ -50,6 +56,32 @@ public class TicketModel implements Serializable, Comparable<TicketModel> {
                }\r
        }\r
 \r
+       @Override\r
+       public int hashCode() {\r
+               return id.hashCode();\r
+       }\r
+\r
+       @Override\r
+       public boolean equals(Object o) {\r
+               if (o instanceof TicketModel) {\r
+                       TicketModel other = (TicketModel) o;\r
+                       return id.equals(other.id);\r
+               }\r
+               return super.equals(o);\r
+       }\r
+\r
+       @Override\r
+       public int compareTo(TicketModel o) {\r
+               return date.compareTo(o.date);\r
+       }\r
+\r
+       /**\r
+        * Comment is a serializable model class that represents a Ticgit ticket\r
+        * comment.\r
+        * \r
+        * @author James Moger\r
+        * \r
+        */\r
        public static class Comment implements Serializable, Comparable<Comment> {\r
 \r
                private static final long serialVersionUID = 1L;\r
@@ -84,23 +116,4 @@ public class TicketModel implements Serializable, Comparable<TicketModel> {
                        return date.compareTo(o.date);\r
                }\r
        }\r
-\r
-       @Override\r
-       public int hashCode() {\r
-               return id.hashCode();\r
-       }\r
-\r
-       @Override\r
-       public boolean equals(Object o) {\r
-               if (o instanceof TicketModel) {\r
-                       TicketModel other = (TicketModel) o;\r
-                       return id.equals(other.id);\r
-               }\r
-               return super.equals(o);\r
-       }\r
-\r
-       @Override\r
-       public int compareTo(TicketModel o) {\r
-               return date.compareTo(o.date);\r
-       }\r
 }\r

diff --git a/src/com/gitblit/models/UserModel.java b/src/com/gitblit/models/UserModel.java
index fd355fbb9441b251589e768ea514d74f83d82245..aeeecf4bd132ca75829b29dedfb30b84fc23d990 100644 (file)
--- a/src/com/gitblit/models/UserModel.java
+++ b/src/com/gitblit/models/UserModel.java
@@ -20,6 +20,14 @@ import java.security.Principal;
 import java.util.ArrayList;\r
 import java.util.List;\r
 \r
+/**\r
+ * UserModel is a serializable model class that represents a user and the user's\r
+ * restricted repository memberships. Instances of UserModels are also used as\r
+ * servlet user principals.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class UserModel implements Principal, Serializable {\r
 \r
        private static final long serialVersionUID = 1L;\r

diff --git a/src/com/gitblit/utils/ByteFormat.java b/src/com/gitblit/utils/ByteFormat.java
index ea198de0f381a7d02a939b92261cd3829759f4e1..f4c05cd52c644b4b2a4345160163f7a52a9208cb 100644 (file)
--- a/src/com/gitblit/utils/ByteFormat.java
+++ b/src/com/gitblit/utils/ByteFormat.java
@@ -20,6 +20,13 @@ import java.text.FieldPosition;
 import java.text.Format;
 import java.text.ParsePosition;
 
+/**
+ * ByteFormat is a formatter which takes numbers and returns filesizes in bytes,
+ * kilobytes, megabytes, or gigabytes.
+ * 
+ * @author James Moger
+ * 
+ */
 public class ByteFormat extends Format {
 
        private static final long serialVersionUID = 1L;

diff --git a/src/com/gitblit/utils/DiffUtils.java b/src/com/gitblit/utils/DiffUtils.java
index c1401f962d79eb9b5a72dc1276d3ca4368bd5678..beeb5323f96fc234e05350455789686eb24639f6 100644 (file)
--- a/src/com/gitblit/utils/DiffUtils.java
+++ b/src/com/gitblit/utils/DiffUtils.java
@@ -30,13 +30,20 @@ import org.eclipse.jgit.lib.Repository;
 import org.eclipse.jgit.revwalk.RevCommit;\r
 import org.eclipse.jgit.revwalk.RevTree;\r
 import org.eclipse.jgit.revwalk.RevWalk;\r
-import org.eclipse.jgit.treewalk.TreeWalk;\r
-import org.eclipse.jgit.treewalk.filter.TreeFilter;\r
 import org.slf4j.Logger;\r
 import org.slf4j.LoggerFactory;\r
 \r
 import com.gitblit.models.AnnotatedLine;\r
 \r
+/**\r
+ * DiffUtils is a class of utility methods related to diff, patch, and blame.\r
+ * \r
+ * The diff methods support pluggable diff output types like Gitblit, Gitweb,\r
+ * and Plain.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class DiffUtils {\r
 \r
        private static final Logger LOGGER = LoggerFactory.getLogger(DiffUtils.class);\r
@@ -54,43 +61,67 @@ public class DiffUtils {
                }\r
        }\r
 \r
-       public static String getCommitDiff(Repository r, RevCommit commit, DiffOutputType outputType) {\r
-               return getDiff(r, null, commit, null, outputType);\r
+       /**\r
+        * Returns the complete diff of the specified commit compared to its primary\r
+        * parent.\r
+        * \r
+        * @param repository\r
+        * @param commit\r
+        * @param outputType\r
+        * @return the diff as a string\r
+        */\r
+       public static String getCommitDiff(Repository repository, RevCommit commit,\r
+                       DiffOutputType outputType) {\r
+               return getDiff(repository, null, commit, null, outputType);\r
        }\r
 \r
-       public static String getDiff(Repository r, RevCommit commit, String path,\r
+       /**\r
+        * Returns the diff for the specified file or folder from the specified\r
+        * commit compared to its primary parent.\r
+        * \r
+        * @param repository\r
+        * @param commit\r
+        * @param path\r
+        * @param outputType\r
+        * @return the diff as a string\r
+        */\r
+       public static String getDiff(Repository repository, RevCommit commit, String path,\r
                        DiffOutputType outputType) {\r
-               return getDiff(r, null, commit, path, outputType);\r
+               return getDiff(repository, null, commit, path, outputType);\r
        }\r
 \r
-       public static String getDiff(Repository r, RevCommit baseCommit, RevCommit commit,\r
+       /**\r
+        * Returns the complete diff between the two specified commits.\r
+        * \r
+        * @param repository\r
+        * @param baseCommit\r
+        * @param commit\r
+        * @param outputType\r
+        * @return the diff as a string\r
+        */\r
+       public static String getDiff(Repository repository, RevCommit baseCommit, RevCommit commit,\r
                        DiffOutputType outputType) {\r
-               return getDiff(r, baseCommit, commit, null, outputType);\r
+               return getDiff(repository, baseCommit, commit, null, outputType);\r
        }\r
 \r
-       public static String getDiff(Repository r, RevCommit baseCommit, RevCommit commit, String path,\r
-                       DiffOutputType outputType) {\r
+       /**\r
+        * Returns the diff between two commits for the specified file.\r
+        * \r
+        * @param repository\r
+        * @param baseCommit\r
+        *            if base commit is null the diff is to the primary parent of\r
+        *            the commit.\r
+        * @param commit\r
+        * @param path\r
+        *            if the path is specified, the diff is restricted to that file\r
+        *            or folder. if unspecified, the diff is for the entire commit.\r
+        * @param outputType\r
+        * @return the diff as a string\r
+        */\r
+       public static String getDiff(Repository repository, RevCommit baseCommit, RevCommit commit,\r
+                       String path, DiffOutputType outputType) {\r
                String diff = null;\r
                try {\r
-                       RevTree baseTree;\r
-                       if (baseCommit == null) {\r
-                               final RevWalk rw = new RevWalk(r);\r
-                               RevCommit parent = rw.parseCommit(commit.getParent(0).getId());\r
-                               rw.dispose();\r
-                               baseTree = parent.getTree();\r
-                       } else {\r
-                               baseTree = baseCommit.getTree();\r
-                       }\r
-\r
-                       RevTree commitTree = commit.getTree();\r
-\r
-                       final TreeWalk walk = new TreeWalk(r);\r
-                       walk.reset();\r
-                       walk.setRecursive(true);\r
-                       walk.addTree(baseTree);\r
-                       walk.addTree(commitTree);\r
-                       walk.setFilter(TreeFilter.ANY_DIFF);\r
-\r
                        final ByteArrayOutputStream os = new ByteArrayOutputStream();\r
                        RawTextComparator cmp = RawTextComparator.DEFAULT;\r
                        DiffFormatter df;\r
@@ -106,9 +137,21 @@ public class DiffUtils {
                                df = new DiffFormatter(os);\r
                                break;\r
                        }\r
-                       df.setRepository(r);\r
+                       df.setRepository(repository);\r
                        df.setDiffComparator(cmp);\r
                        df.setDetectRenames(true);\r
+\r
+                       RevTree commitTree = commit.getTree();\r
+                       RevTree baseTree;\r
+                       if (baseCommit == null) {\r
+                               final RevWalk rw = new RevWalk(repository);\r
+                               RevCommit parent = rw.parseCommit(commit.getParent(0).getId());\r
+                               rw.dispose();\r
+                               baseTree = parent.getTree();\r
+                       } else {\r
+                               baseTree = baseCommit.getTree();\r
+                       }\r
+\r
                        List<DiffEntry> diffEntries = df.scan(baseTree, commitTree);\r
                        if (path != null && path.length() > 0) {\r
                                for (DiffEntry diffEntry : diffEntries) {\r
@@ -133,33 +176,42 @@ public class DiffUtils {
                return diff;\r
        }\r
 \r
-       public static String getCommitPatch(Repository r, RevCommit baseCommit, RevCommit commit,\r
-                       String path) {\r
+       /**\r
+        * Returns the diff between the two commits for the specified file or folder\r
+        * formatted as a patch.\r
+        * \r
+        * @param repository\r
+        * @param baseCommit\r
+        *            if base commit is unspecified, the patch is generated against\r
+        *            the primary parent of the specified commit.\r
+        * @param commit\r
+        * @param path\r
+        *            if path is specified, the patch is generated only for the\r
+        *            specified file or folder. if unspecified, the patch is\r
+        *            generated for the entire diff between the two commits.\r
+        * @return patch as a string\r
+        */\r
+       public static String getCommitPatch(Repository repository, RevCommit baseCommit,\r
+                       RevCommit commit, String path) {\r
                String diff = null;\r
                try {\r
+                       final ByteArrayOutputStream os = new ByteArrayOutputStream();\r
+                       RawTextComparator cmp = RawTextComparator.DEFAULT;\r
+                       PatchFormatter df = new PatchFormatter(os);\r
+                       df.setRepository(repository);\r
+                       df.setDiffComparator(cmp);\r
+                       df.setDetectRenames(true);\r
+\r
+                       RevTree commitTree = commit.getTree();\r
                        RevTree baseTree;\r
                        if (baseCommit == null) {\r
-                               final RevWalk rw = new RevWalk(r);\r
+                               final RevWalk rw = new RevWalk(repository);\r
                                RevCommit parent = rw.parseCommit(commit.getParent(0).getId());\r
                                baseTree = parent.getTree();\r
                        } else {\r
                                baseTree = baseCommit.getTree();\r
                        }\r
-                       RevTree commitTree = commit.getTree();\r
-\r
-                       final TreeWalk walk = new TreeWalk(r);\r
-                       walk.reset();\r
-                       walk.setRecursive(true);\r
-                       walk.addTree(baseTree);\r
-                       walk.addTree(commitTree);\r
-                       walk.setFilter(TreeFilter.ANY_DIFF);\r
 \r
-                       final ByteArrayOutputStream os = new ByteArrayOutputStream();\r
-                       RawTextComparator cmp = RawTextComparator.DEFAULT;\r
-                       PatchFormatter df = new PatchFormatter(os);\r
-                       df.setRepository(r);\r
-                       df.setDiffComparator(cmp);\r
-                       df.setDetectRenames(true);\r
                        List<DiffEntry> diffEntries = df.scan(baseTree, commitTree);\r
                        if (path != null && path.length() > 0) {\r
                                for (DiffEntry diffEntry : diffEntries) {\r
@@ -179,15 +231,24 @@ public class DiffUtils {
                return diff;\r
        }\r
 \r
-       public static List<AnnotatedLine> blame(Repository r, String blobPath, String objectId) {\r
+       /**\r
+        * Returns the list of lines in the specified source file annotated with the\r
+        * source commit metadata.\r
+        * \r
+        * @param repository\r
+        * @param blobPath\r
+        * @param objectId\r
+        * @return list of annotated lines\r
+        */\r
+       public static List<AnnotatedLine> blame(Repository repository, String blobPath, String objectId) {\r
                List<AnnotatedLine> lines = new ArrayList<AnnotatedLine>();\r
                try {\r
                        if (StringUtils.isEmpty(objectId)) {\r
                                objectId = Constants.HEAD;\r
                        }\r
-                       BlameCommand blameCommand = new BlameCommand(r);\r
+                       BlameCommand blameCommand = new BlameCommand(repository);\r
                        blameCommand.setFilePath(blobPath);\r
-                       blameCommand.setStartCommit(r.resolve(objectId));\r
+                       blameCommand.setStartCommit(repository.resolve(objectId));\r
                        BlameResult blameResult = blameCommand.call();\r
                        RawText rawText = blameResult.getResultContents();\r
                        int length = rawText.size();\r

diff --git a/src/com/gitblit/utils/FileUtils.java b/src/com/gitblit/utils/FileUtils.java
index 3cfe6894c66ab33cd9736af10ca06cc6e804a641..468b2a8086b9a748479f55a6812a1271a838f6db 100644 (file)
--- a/src/com/gitblit/utils/FileUtils.java
+++ b/src/com/gitblit/utils/FileUtils.java
@@ -34,7 +34,7 @@ public class FileUtils {
         * \r
         * @param file\r
         * @param lineEnding\r
-        * @return\r
+        * @return the string content of the file\r
         */\r
        public static String readContent(File file, String lineEnding) {\r
                StringBuilder sb = new StringBuilder();\r

diff --git a/src/com/gitblit/utils/GitBlitDiffFormatter.java b/src/com/gitblit/utils/GitBlitDiffFormatter.java
index 144136128460beab0cf8ac7b4ea04ff0f0d915b5..0e393fef872fd594e32fa79691fda0f833d54048 100644 (file)
--- a/src/com/gitblit/utils/GitBlitDiffFormatter.java
+++ b/src/com/gitblit/utils/GitBlitDiffFormatter.java
@@ -21,6 +21,12 @@ import java.io.OutputStream;
 \r
 import org.eclipse.jgit.diff.RawText;\r
 \r
+/**\r
+ * Generates an html snippet of a diff in Gitblit's style.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class GitBlitDiffFormatter extends GitWebDiffFormatter {\r
 \r
        private final OutputStream os;\r

diff --git a/src/com/gitblit/utils/GitWebDiffFormatter.java b/src/com/gitblit/utils/GitWebDiffFormatter.java
index b998259bdac0021ea790aab2284e957b8825ccbc..00ea121c64921a3f33d03d394b4f367b852eaaca 100644 (file)
--- a/src/com/gitblit/utils/GitWebDiffFormatter.java
+++ b/src/com/gitblit/utils/GitWebDiffFormatter.java
@@ -24,6 +24,12 @@ import java.io.OutputStream;
 import org.eclipse.jgit.diff.DiffFormatter;\r
 import org.eclipse.jgit.diff.RawText;\r
 \r
+/**\r
+ * Returns an html snippet of the diff in the standard Gitweb style.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class GitWebDiffFormatter extends DiffFormatter {\r
 \r
        private final OutputStream os;\r

diff --git a/src/com/gitblit/utils/MarkdownUtils.java b/src/com/gitblit/utils/MarkdownUtils.java
index 697fa99b9db65066e0dccc82ff81bc6ba37e5954..c7c1f9fe94aaa3f0137ea7fd361e782484ee75e5 100644 (file)
--- a/src/com/gitblit/utils/MarkdownUtils.java
+++ b/src/com/gitblit/utils/MarkdownUtils.java
@@ -23,8 +23,21 @@ import java.io.StringWriter;
 import org.tautua.markdownpapers.Markdown;\r
 import org.tautua.markdownpapers.parser.ParseException;\r
 \r
+/**\r
+ * Utility methods for transforming raw markdown text to html.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class MarkdownUtils {\r
 \r
+       /**\r
+        * Returns the html version of the markdown source text.\r
+        * \r
+        * @param markdown\r
+        * @return html version of markdown text\r
+        * @throws java.text.ParseException\r
+        */\r
        public static String transformMarkdown(String markdown) throws java.text.ParseException {\r
                try {\r
                        return transformMarkdown(new StringReader(markdown));\r
@@ -33,6 +46,14 @@ public class MarkdownUtils {
                }\r
        }\r
 \r
+       /**\r
+        * Returns the html version of the markdown source reader. The reader is\r
+        * closed regardless of success or failure.\r
+        * \r
+        * @param markdownReader\r
+        * @return html version of the markdown text\r
+        * @throws java.text.ParseException\r
+        */\r
        public static String transformMarkdown(Reader markdownReader) throws java.text.ParseException {\r
                // Read raw markdown content and transform it to html\r
                StringWriter writer = new StringWriter();\r

diff --git a/src/com/gitblit/utils/MetricUtils.java b/src/com/gitblit/utils/MetricUtils.java
index 85ef89f1127b5c4c44fcf15a95a670a5f59cc48b..acdacc4d3108162cf1abfd425a9d88b94b466a30 100644 (file)
--- a/src/com/gitblit/utils/MetricUtils.java
+++ b/src/com/gitblit/utils/MetricUtils.java
@@ -35,33 +35,58 @@ import org.slf4j.LoggerFactory;
 import com.gitblit.models.Metric;\r
 import com.gitblit.models.RefModel;\r
 \r
+/**\r
+ * Utility class for collecting metrics on a branch, tag, or other ref within\r
+ * the repository.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class MetricUtils {\r
 \r
        private static final Logger LOGGER = LoggerFactory.getLogger(MetricUtils.class);\r
 \r
-       public static List<Metric> getDateMetrics(Repository r, String objectId, boolean includeTotal,\r
-                       String format) {\r
+       /**\r
+        * Returns the list of metrics for the specified commit reference, branch,\r
+        * or tag within the repository. If includeTotal is true, the total of all\r
+        * the metrics will be included as the first element in the returned list.\r
+        * \r
+        * If the dateformat is unspecified an attempt is made to determine an\r
+        * appropriate date format by determining the time difference between the\r
+        * first commit on the branch and the most recent commit. This assumes that\r
+        * the commits are linear.\r
+        * \r
+        * @param repository\r
+        * @param objectId\r
+        *            if null or empty, HEAD is assumed.\r
+        * @param includeTotal\r
+        * @param dateFormat\r
+        * @return list of metrics\r
+        */\r
+       public static List<Metric> getDateMetrics(Repository repository, String objectId,\r
+                       boolean includeTotal, String dateFormat) {\r
                Metric total = new Metric("TOTAL");\r
                final Map<String, Metric> metricMap = new HashMap<String, Metric>();\r
                if (StringUtils.isEmpty(objectId)) {\r
                        objectId = Constants.HEAD;\r
                }\r
-               if (JGitUtils.hasCommits(r)) {\r
-                       final List<RefModel> tags = JGitUtils.getTags(r, true, -1);\r
+               if (JGitUtils.hasCommits(repository)) {\r
+                       final List<RefModel> tags = JGitUtils.getTags(repository, true, -1);\r
                        final Map<ObjectId, RefModel> tagMap = new HashMap<ObjectId, RefModel>();\r
                        for (RefModel tag : tags) {\r
                                tagMap.put(tag.getReferencedObjectId(), tag);\r
                        }\r
+                       RevWalk revWalk = null;\r
                        try {\r
-                               RevWalk walk = new RevWalk(r);\r
-                               ObjectId object = r.resolve(objectId);\r
-                               RevCommit lastCommit = walk.parseCommit(object);\r
-                               walk.markStart(lastCommit);\r
+                               revWalk = new RevWalk(repository);\r
+                               ObjectId object = repository.resolve(objectId);\r
+                               RevCommit lastCommit = revWalk.parseCommit(object);\r
+                               revWalk.markStart(lastCommit);\r
 \r
                                DateFormat df;\r
-                               if (StringUtils.isEmpty(format)) {\r
+                               if (StringUtils.isEmpty(dateFormat)) {\r
                                        // dynamically determine date format\r
-                                       RevCommit firstCommit = JGitUtils.getFirstCommit(r, Constants.HEAD);\r
+                                       RevCommit firstCommit = JGitUtils.getFirstCommit(repository, Constants.HEAD);\r
                                        int diffDays = (lastCommit.getCommitTime() - firstCommit.getCommitTime())\r
                                                        / (60 * 60 * 24);\r
                                        total.duration = diffDays;\r
@@ -74,10 +99,10 @@ public class MetricUtils {
                                        }\r
                                } else {\r
                                        // use specified date format\r
-                                       df = new SimpleDateFormat(format);\r
+                                       df = new SimpleDateFormat(dateFormat);\r
                                }\r
 \r
-                               Iterable<RevCommit> revlog = walk;\r
+                               Iterable<RevCommit> revlog = revWalk;\r
                                for (RevCommit rev : revlog) {\r
                                        Date d = JGitUtils.getCommitDate(rev);\r
                                        String p = df.format(d);\r
@@ -94,6 +119,10 @@ public class MetricUtils {
                                }\r
                        } catch (Throwable t) {\r
                                LOGGER.error("Failed to mine log history for date metrics", t);\r
+                       } finally {\r
+                               if (revWalk != null) {\r
+                                       revWalk.dispose();\r
+                               }\r
                        }\r
                }\r
                List<String> keys = new ArrayList<String>(metricMap.keySet());\r
@@ -108,22 +137,33 @@ public class MetricUtils {
                return metrics;\r
        }\r
 \r
-       public static List<Metric> getAuthorMetrics(Repository r, String objectId, boolean byEmail) {\r
+       /**\r
+        * Returns a list of author metrics for the specified repository.\r
+        * \r
+        * @param repository\r
+        * @param objectId\r
+        *            if null or empty, HEAD is assumed.\r
+        * @param byEmailAddress\r
+        *            group metrics by author email address otherwise by author name\r
+        * @return list of metrics\r
+        */\r
+       public static List<Metric> getAuthorMetrics(Repository repository, String objectId,\r
+                       boolean byEmailAddress) {\r
                final Map<String, Metric> metricMap = new HashMap<String, Metric>();\r
                if (StringUtils.isEmpty(objectId)) {\r
                        objectId = Constants.HEAD;\r
                }\r
-               if (JGitUtils.hasCommits(r)) {\r
+               if (JGitUtils.hasCommits(repository)) {\r
                        try {\r
-                               RevWalk walk = new RevWalk(r);\r
-                               ObjectId object = r.resolve(objectId);\r
+                               RevWalk walk = new RevWalk(repository);\r
+                               ObjectId object = repository.resolve(objectId);\r
                                RevCommit lastCommit = walk.parseCommit(object);\r
                                walk.markStart(lastCommit);\r
 \r
                                Iterable<RevCommit> revlog = walk;\r
                                for (RevCommit rev : revlog) {\r
                                        String p;\r
-                                       if (byEmail) {\r
+                                       if (byEmailAddress) {\r
                                                p = rev.getAuthorIdent().getEmailAddress().toLowerCase();\r
                                                if (StringUtils.isEmpty(p)) {\r
                                                        p = rev.getAuthorIdent().getName().toLowerCase();\r

diff --git a/src/com/gitblit/utils/PatchFormatter.java b/src/com/gitblit/utils/PatchFormatter.java
index daa15aae045be89489a0d5e02cc96a8f88f70b8f..925595618ccdf4e78184ab47080ac04629a141a5 100644 (file)
--- a/src/com/gitblit/utils/PatchFormatter.java
+++ b/src/com/gitblit/utils/PatchFormatter.java
@@ -30,6 +30,12 @@ import org.eclipse.jgit.revwalk.RevCommit;
 \r
 import com.gitblit.Constants;\r
 \r
+/**\r
+ * A diff formatter that outputs standard patch content.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class PatchFormatter extends DiffFormatter {\r
 \r
        private final OutputStream os;\r

diff --git a/src/com/gitblit/utils/StringUtils.java b/src/com/gitblit/utils/StringUtils.java
index 219699fc3e36a955e00653c1d84c88444374ed03..bb1928a2616043a8a930d64e6dd66300fd4f4a22 100644 (file)
--- a/src/com/gitblit/utils/StringUtils.java
+++ b/src/com/gitblit/utils/StringUtils.java
@@ -22,18 +22,44 @@ import java.util.ArrayList;
 import java.util.List;\r
 import java.util.regex.PatternSyntaxException;\r
 \r
+/**\r
+ * Utility class of string functions.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class StringUtils {\r
 \r
        public static final String MD5_TYPE = "MD5:";\r
 \r
+       /**\r
+        * Returns true if the string is null or empty.\r
+        * \r
+        * @param value\r
+        * @return true if string is null or empty\r
+        */\r
        public static boolean isEmpty(String value) {\r
                return value == null || value.trim().length() == 0;\r
        }\r
 \r
+       /**\r
+        * Replaces carriage returns and line feeds with html line breaks.\r
+        * \r
+        * @param string\r
+        * @return plain text with html line breaks\r
+        */\r
        public static String breakLinesForHtml(String string) {\r
                return string.replace("\r\n", "<br/>").replace("\r", "<br/>").replace("\n", "<br/>");\r
        }\r
 \r
+       /**\r
+        * Prepare text for html presentation. Replace sensitive characters with\r
+        * html entities.\r
+        * \r
+        * @param inStr\r
+        * @param changeSpace\r
+        * @return plain text escaped for html\r
+        */\r
        public static String escapeForHtml(String inStr, boolean changeSpace) {\r
                StringBuffer retStr = new StringBuffer();\r
                int i = 0;\r
@@ -58,11 +84,23 @@ public class StringUtils {
                return retStr.toString();\r
        }\r
 \r
+       /**\r
+        * Decode html entities back into plain text characters.\r
+        * \r
+        * @param inStr\r
+        * @return returns plain text from html\r
+        */\r
        public static String decodeFromHtml(String inStr) {\r
                return inStr.replace("&amp;", "&").replace("&lt;", "<").replace("&gt;", ">")\r
                                .replace("&quot;", "\"").replace("&nbsp;", " ");\r
        }\r
 \r
+       /**\r
+        * Encodes a url parameter by escaping troublesome characters.\r
+        * \r
+        * @param inStr\r
+        * @return properly escaped url\r
+        */\r
        public static String encodeURL(String inStr) {\r
                StringBuffer retStr = new StringBuffer();\r
                int i = 0;\r
@@ -79,10 +117,24 @@ public class StringUtils {
                return retStr.toString();\r
        }\r
 \r
+       /**\r
+        * Flatten the list of strings into a single string with a space separator.\r
+        * \r
+        * @param values\r
+        * @return flattened list\r
+        */\r
        public static String flattenStrings(List<String> values) {\r
                return flattenStrings(values, " ");\r
        }\r
 \r
+       /**\r
+        * Flatten the list of strings into a single string with the specified\r
+        * separator.\r
+        * \r
+        * @param values\r
+        * @param separator\r
+        * @return flattened list\r
+        */\r
        public static String flattenStrings(List<String> values, String separator) {\r
                StringBuilder sb = new StringBuilder();\r
                for (String value : values) {\r
@@ -91,6 +143,15 @@ public class StringUtils {
                return sb.toString().trim();\r
        }\r
 \r
+       /**\r
+        * Returns a string trimmed to a maximum length with trailing ellipses. If\r
+        * the string length is shorter than the max, the original string is\r
+        * returned.\r
+        * \r
+        * @param value\r
+        * @param max\r
+        * @return trimmed string\r
+        */\r
        public static String trimString(String value, int max) {\r
                if (value.length() <= max) {\r
                        return value;\r
@@ -98,10 +159,25 @@ public class StringUtils {
                return value.substring(0, max - 3) + "...";\r
        }\r
 \r
+       /**\r
+        * Returns a trimmed shortlog message.\r
+        * \r
+        * @param string\r
+        * @return trimmed shortlog message\r
+        */\r
        public static String trimShortLog(String string) {\r
                return trimString(string, 60);\r
        }\r
 \r
+       /**\r
+        * Left pad a string with the specified character, if the string length is\r
+        * less than the specified length.\r
+        * \r
+        * @param input\r
+        * @param length\r
+        * @param pad\r
+        * @return left-padded string\r
+        */\r
        public static String leftPad(String input, int length, char pad) {\r
                if (input.length() < length) {\r
                        StringBuilder sb = new StringBuilder();\r
@@ -114,6 +190,15 @@ public class StringUtils {
                return input;\r
        }\r
 \r
+       /**\r
+        * Right pad a string with the specified character, if the string length is\r
+        * less then the specified length.\r
+        * \r
+        * @param input\r
+        * @param length\r
+        * @param pad\r
+        * @return right-padded string\r
+        */\r
        public static String rightPad(String input, int length, char pad) {\r
                if (input.length() < length) {\r
                        StringBuilder sb = new StringBuilder();\r
@@ -126,6 +211,12 @@ public class StringUtils {
                return input;\r
        }\r
 \r
+       /**\r
+        * Calculates the SHA1 of the string.\r
+        * \r
+        * @param text\r
+        * @return sha1 of the string\r
+        */\r
        public static String getSHA1(String text) {\r
                try {\r
                        byte[] bytes = text.getBytes("iso-8859-1");\r
@@ -135,6 +226,12 @@ public class StringUtils {
                }\r
        }\r
 \r
+       /**\r
+        * Calculates the SHA1 of the byte array.\r
+        * \r
+        * @param bytes\r
+        * @return sha1 of the byte array\r
+        */\r
        public static String getSHA1(byte[] bytes) {\r
                try {\r
                        MessageDigest md = MessageDigest.getInstance("SHA-1");\r
@@ -146,6 +243,12 @@ public class StringUtils {
                }\r
        }\r
 \r
+       /**\r
+        * Calculates the MD5 of the string.\r
+        * \r
+        * @param string\r
+        * @return md5 of the string\r
+        */\r
        public static String getMD5(String string) {\r
                try {\r
                        MessageDigest md = MessageDigest.getInstance("MD5");\r
@@ -160,6 +263,12 @@ public class StringUtils {
                }\r
        }\r
 \r
+       /**\r
+        * Returns the hex representation of the byte array.\r
+        * \r
+        * @param bytes\r
+        * @return byte array as hex string\r
+        */\r
        private static String toHex(byte[] bytes) {\r
                StringBuilder sb = new StringBuilder(bytes.length * 2);\r
                for (int i = 0; i < bytes.length; i++) {\r
@@ -171,6 +280,13 @@ public class StringUtils {
                return sb.toString();\r
        }\r
 \r
+       /**\r
+        * Returns the root path of the specified path. Returns a blank string if\r
+        * there is no root path.\r
+        * \r
+        * @param path\r
+        * @return root path or blank\r
+        */\r
        public static String getRootPath(String path) {\r
                if (path.indexOf('/') > -1) {\r
                        return path.substring(0, path.lastIndexOf('/'));\r
@@ -178,6 +294,14 @@ public class StringUtils {
                return "";\r
        }\r
 \r
+       /**\r
+        * Returns the path remainder after subtracting the basePath from the\r
+        * fullPath.\r
+        * \r
+        * @param basePath\r
+        * @param fullPath\r
+        * @return the relative path\r
+        */\r
        public static String getRelativePath(String basePath, String fullPath) {\r
                String relativePath = fullPath.substring(basePath.length()).replace('\\', '/');\r
                if (relativePath.charAt(0) == '/') {\r
@@ -186,10 +310,23 @@ public class StringUtils {
                return relativePath;\r
        }\r
 \r
+       /**\r
+        * Splits the space-separated string into a list of strings.\r
+        * \r
+        * @param value\r
+        * @return list of strings\r
+        */\r
        public static List<String> getStringsFromValue(String value) {\r
                return getStringsFromValue(value, " ");\r
        }\r
 \r
+       /**\r
+        * Splits the string into a list of string by the specified separator.\r
+        * \r
+        * @param value\r
+        * @param separator\r
+        * @return list of strings\r
+        */\r
        public static List<String> getStringsFromValue(String value, String separator) {\r
                List<String> strings = new ArrayList<String>();\r
                try {\r

diff --git a/src/com/gitblit/utils/SyndicationUtils.java b/src/com/gitblit/utils/SyndicationUtils.java
index 80a1b28859cfaa712392849d2b55252272e6345e..fb40dd566c82a0469013392532bbd0d9e775d34c 100644 (file)
--- a/src/com/gitblit/utils/SyndicationUtils.java
+++ b/src/com/gitblit/utils/SyndicationUtils.java
@@ -35,8 +35,26 @@ import com.sun.syndication.feed.synd.SyndImageImpl;
 import com.sun.syndication.io.FeedException;\r
 import com.sun.syndication.io.SyndFeedOutput;\r
 \r
+/**\r
+ * Utility class for RSS feeds.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class SyndicationUtils {\r
 \r
+       /**\r
+        * Outputs an RSS feed of the list of commits to the outputstream.\r
+        * \r
+        * @param hostUrl\r
+        * @param title\r
+        * @param description\r
+        * @param repository\r
+        * @param commits\r
+        * @param os\r
+        * @throws IOException\r
+        * @throws FeedException\r
+        */\r
        public static void toRSS(String hostUrl, String title, String description, String repository,\r
                        List<RevCommit> commits, OutputStream os) throws IOException, FeedException {\r
 \r

diff --git a/src/com/gitblit/utils/TicgitUtils.java b/src/com/gitblit/utils/TicgitUtils.java
index 48e8558c98449178d3c0188f1b479c86134d2387..87a2b3aeaa62d42c825f15919788b75347d05808 100644 (file)
--- a/src/com/gitblit/utils/TicgitUtils.java
+++ b/src/com/gitblit/utils/TicgitUtils.java
@@ -30,15 +30,28 @@ import com.gitblit.models.RefModel;
 import com.gitblit.models.TicketModel;\r
 import com.gitblit.models.TicketModel.Comment;\r
 \r
+/**\r
+ * Utility class for reading Ticgit issues.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class TicgitUtils {\r
 \r
        static final Logger LOGGER = LoggerFactory.getLogger(TicgitUtils.class);\r
 \r
-       public static RefModel getTicketsBranch(Repository r) {\r
+       /**\r
+        * Returns a RefModel for the Ticgit branch in the repository. If the branch\r
+        * can not be found, null is returned.\r
+        * \r
+        * @param repository\r
+        * @return a refmodel for the ticgit branch or null\r
+        */\r
+       public static RefModel getTicketsBranch(Repository repository) {\r
                RefModel ticgitBranch = null;\r
                try {\r
                        // search for ticgit branch in local heads\r
-                       for (RefModel ref : JGitUtils.getLocalBranches(r, false, -1)) {\r
+                       for (RefModel ref : JGitUtils.getLocalBranches(repository, false, -1)) {\r
                                if (ref.displayName.endsWith("ticgit")) {\r
                                        ticgitBranch = ref;\r
                                        break;\r
@@ -47,7 +60,7 @@ public class TicgitUtils {
 \r
                        // search for ticgit branch in remote heads\r
                        if (ticgitBranch == null) {\r
-                               for (RefModel ref : JGitUtils.getRemoteBranches(r, false, -1)) {\r
+                               for (RefModel ref : JGitUtils.getRemoteBranches(repository, false, -1)) {\r
                                        if (ref.displayName.endsWith("ticgit")) {\r
                                                ticgitBranch = ref;\r
                                                break;\r
@@ -60,19 +73,25 @@ public class TicgitUtils {
                return ticgitBranch;\r
        }\r
 \r
-       public static List<TicketModel> getTickets(Repository r) {\r
-               RefModel ticgitBranch = getTicketsBranch(r);\r
+       /**\r
+        * Returns a list of all tickets in the ticgit branch of the repository.\r
+        * \r
+        * @param repository\r
+        * @return list of tickets\r
+        */\r
+       public static List<TicketModel> getTickets(Repository repository) {\r
+               RefModel ticgitBranch = getTicketsBranch(repository);\r
                if (ticgitBranch == null) {\r
                        return null;\r
                }\r
                RevCommit commit = (RevCommit) ticgitBranch.referencedObject;\r
-               List<PathModel> paths = JGitUtils.getFilesInPath(r, null, commit);\r
+               List<PathModel> paths = JGitUtils.getFilesInPath(repository, null, commit);\r
                List<TicketModel> tickets = new ArrayList<TicketModel>();\r
                for (PathModel ticketFolder : paths) {\r
                        if (ticketFolder.isTree()) {\r
                                try {\r
                                        TicketModel t = new TicketModel(ticketFolder.name);\r
-                                       readTicketContents(r, ticgitBranch, t);\r
+                                       loadTicketContents(repository, ticgitBranch, t);\r
                                        tickets.add(t);\r
                                } catch (Throwable t) {\r
                                        LOGGER.error("Failed to get a ticket!", t);\r
@@ -84,12 +103,20 @@ public class TicgitUtils {
                return tickets;\r
        }\r
 \r
-       public static TicketModel getTicket(Repository r, String ticketFolder) {\r
-               RefModel ticketsBranch = getTicketsBranch(r);\r
+       /**\r
+        * Returns a TicketModel for the specified ticgit ticket. Returns null if\r
+        * the ticket does not exist or some other error occurs.\r
+        * \r
+        * @param repository\r
+        * @param ticketFolder\r
+        * @return a ticket\r
+        */\r
+       public static TicketModel getTicket(Repository repository, String ticketFolder) {\r
+               RefModel ticketsBranch = getTicketsBranch(repository);\r
                if (ticketsBranch != null) {\r
                        try {\r
                                TicketModel ticket = new TicketModel(ticketFolder);\r
-                               readTicketContents(r, ticketsBranch, ticket);\r
+                               loadTicketContents(repository, ticketsBranch, ticket);\r
                                return ticket;\r
                        } catch (Throwable t) {\r
                                LOGGER.error("Failed to get ticket " + ticketFolder, t);\r
@@ -98,11 +125,20 @@ public class TicgitUtils {
                return null;\r
        }\r
 \r
-       private static void readTicketContents(Repository r, RefModel ticketsBranch, TicketModel ticket) {\r
+       /**\r
+        * Loads the contents of the ticket.\r
+        * \r
+        * @param repository\r
+        * @param ticketsBranch\r
+        * @param ticket\r
+        */\r
+       private static void loadTicketContents(Repository repository, RefModel ticketsBranch,\r
+                       TicketModel ticket) {\r
                RevCommit commit = (RevCommit) ticketsBranch.referencedObject;\r
-               List<PathModel> ticketFiles = JGitUtils.getFilesInPath(r, ticket.name, commit);\r
+               List<PathModel> ticketFiles = JGitUtils.getFilesInPath(repository, ticket.name, commit);\r
                for (PathModel file : ticketFiles) {\r
-                       String content = JGitUtils.getStringContent(r, commit.getTree(), file.path).trim();\r
+                       String content = JGitUtils.getStringContent(repository, commit.getTree(), file.path)\r
+                                       .trim();\r
                        if (file.name.equals("TICKET_ID")) {\r
                                ticket.id = content;\r
                        } else if (file.name.equals("TITLE")) {\r

diff --git a/src/com/gitblit/utils/TimeUtils.java b/src/com/gitblit/utils/TimeUtils.java
index dcb60ab0b9fcd1d10ee2f943165ce22586827fa7..ad814636efb9eee25797bbc798004bda486bc1d1 100644 (file)
--- a/src/com/gitblit/utils/TimeUtils.java
+++ b/src/com/gitblit/utils/TimeUtils.java
@@ -18,6 +18,12 @@ package com.gitblit.utils;
 import java.util.Calendar;\r
 import java.util.Date;\r
 \r
+/**\r
+ * Utility class of time functions.\r
+ * \r
+ * @author James Moger\r
+ * \r
+ */\r
 public class TimeUtils {\r
        public static final long MIN = 1000 * 60L;\r
 \r
@@ -29,10 +35,22 @@ public class TimeUtils {
 \r
        public static final long ONEYEAR = ONEDAY * 365L;\r
 \r
+       /**\r
+        * Returns true if date is today.\r
+        * \r
+        * @param date\r
+        * @return true if date is today\r
+        */\r
        public static boolean isToday(Date date) {\r
                return (System.currentTimeMillis() - date.getTime()) < ONEDAY;\r
        }\r
 \r
+       /**\r
+        * Returns true if date is yesterday.\r
+        * \r
+        * @param date\r
+        * @return true if date is yesterday\r
+        */\r
        public static boolean isYesterday(Date date) {\r
                Calendar cal = Calendar.getInstance();\r
                cal.setTime(date);\r
@@ -40,6 +58,13 @@ public class TimeUtils {
                return (System.currentTimeMillis() - cal.getTimeInMillis()) < ONEDAY;\r
        }\r
 \r
+       /**\r
+        * Returns the string representation of the duration as days, months and/or\r
+        * years.\r
+        * \r
+        * @param days\r
+        * @return duration as string in days, months, and/or years\r
+        */\r
        public static String duration(int days) {\r
                if (days <= 60) {\r
                        return days + (days > 1 ? " days" : " day");\r
@@ -69,6 +94,15 @@ public class TimeUtils {
                }\r
        }\r
 \r
+       /**\r
+        * Returns the number of minutes ago between the start time and the end\r
+        * time.\r
+        * \r
+        * @param date\r
+        * @param endTime\r
+        * @param roundup\r
+        * @return difference in minutes\r
+        */\r
        public static int minutesAgo(Date date, long endTime, boolean roundup) {\r
                long diff = endTime - date.getTime();\r
                int mins = (int) (diff / MIN);\r
@@ -78,10 +112,24 @@ public class TimeUtils {
                return mins;\r
        }\r
 \r
+       /**\r
+        * Return the difference in minutes between now and the date.\r
+        * \r
+        * @param date\r
+        * @param roundup\r
+        * @return minutes ago\r
+        */\r
        public static int minutesAgo(Date date, boolean roundup) {\r
                return minutesAgo(date, System.currentTimeMillis(), roundup);\r
        }\r
 \r
+       /**\r
+        * Return the difference in hours between now and the date.\r
+        * \r
+        * @param date\r
+        * @param roundup\r
+        * @return hours ago\r
+        */\r
        public static int hoursAgo(Date date, boolean roundup) {\r
                long diff = System.currentTimeMillis() - date.getTime();\r
                int hours = (int) (diff / ONEHOUR);\r
@@ -91,6 +139,13 @@ public class TimeUtils {
                return hours;\r
        }\r
 \r
+       /**\r
+        * Return the difference in days between now and the date.\r
+        * \r
+        * @param date\r
+        * @param roundup\r
+        * @return days ago\r
+        */\r
        public static int daysAgo(Date date, boolean roundup) {\r
                long diff = System.currentTimeMillis() - date.getTime();\r
                int days = (int) (diff / ONEDAY);\r
@@ -100,14 +155,35 @@ public class TimeUtils {
                return days;\r
        }\r
 \r
+       /**\r
+        * Returns the string representation of the duration between now and the\r
+        * date.\r
+        * \r
+        * @param date\r
+        * @return duration as a string\r
+        */\r
        public static String timeAgo(Date date) {\r
                return timeAgo(date, false);\r
        }\r
 \r
+       /**\r
+        * Returns the CSS class for the date based on its age from Now.\r
+        * \r
+        * @param date\r
+        * @return the css class\r
+        */\r
        public static String timeAgoCss(Date date) {\r
                return timeAgo(date, true);\r
        }\r
 \r
+       /**\r
+        * Returns the string representation of the duration OR the css class for\r
+        * the duration.\r
+        * \r
+        * @param date\r
+        * @param css\r
+        * @return the string representation of the duration OR the css class\r
+        */\r
        private static String timeAgo(Date date, boolean css) {\r
                String ago = null;\r
                if (isToday(date) || isYesterday(date)) {\r