Comprehensive documentation using JLP.

src/main/com/jdblabs/gtd/Item.groovy

@@ -1,27 +1,75 @@
+/** 
+ * # Item
+ * @author Jonathan Bernard (jdb@jdb-labs.com)
+ * @copyright 2013 [JDB Labs LLC](http://jdb-labs.com)
+ */
 package com.jdblabs.gtd
 
+/**
+ * One Getting Things Done item (a page in David Allen's system). An item is
+ * represented by a file on the filesystem, organized into one of the GTD
+ * folders. The Item can have arbitrarily many properties, which are stored in
+ * the Item file as standard Java properties. By convention the `action`
+ * property is used as the item description (assuming this item is a next
+ * action item). Other important properties include:
+ *
+ * * `outcome`: describes the desired outcome.
+ * * `title`: the item title (optionally used if no `action` is defined).
+ * * `date`: the due date for this item. Remember that we should not use the
+ *   calendar to "schedule" items, but only to represent items which must be
+ *   done by or on that day.
+ * * `details`: more information related to this item.
+ * @org gtd.jdb-labs.com/Item
+ */
 public class Item {
     
     public File file
     public Map gtdProperties = [:]
 
+    /** 
+     * #### constructor
+     * Load an item from a file. The typical pattern for creating new Items is
+     * to create the file first then pass that file to an Item constructor.
+     * Files with no contents are valid GTD items (the file name is used as a
+     * description in lieu of an `action` or `title` property). */
     public Item(File f) {
         this.file = f
 
+        /// Read and parse the item's properties from the file.
         def javaProps = new Properties()
         f.withReader { reader -> javaProps.load(reader) }
+
+        /// Properties are stored as plain text in the file. We use the
+        /// [PropertyHelp](jlp://gtd.jdb-labs.com/PropertyHelp) Enum to
+        /// serialize and deserialize the property objects.
         javaProps.each { k, v -> gtdProperties[k] = PropertyHelp.parse(v) } }
 
+    /** #### `save`
+      * Persist the Item to it's file. */
     public void save() {
         def javaProps = new Properties()
         gtdProperties.each { k, v -> javaProps[k] = PropertyHelp.format(v) }
         file.withOutputStream { os -> javaProps.store(os, "") } }
 
+    /** #### `propertyMissing`
+      * Provide an implementation of the Groovy dynamic [propertyMissing][1]
+      * method to expose the gtdProperties map as properties on the item
+      * itself.
+      *
+      * [1]: http://groovy.codehaus.org/Using+methodMissing+and+propertyMissing
+      */
     public def propertyMissing(String name, def value) {
         gtdProperties[name] = value }
 
     public def propertyMissing(String name) { return gtdProperties[name] }
 
+    /** #### `toString`
+      * Provide a standard description of the item. This is used by the CLI
+      * interface, for example, to directly display GTD items.
+      *
+      * Look first for the `action` property, then `outcome`, then `title`.
+      * Failing to find any of these properties, pretty-print the filename
+      * as a description. */
     public String toString() { 
         if (gtdProperties.action) return gtdProperties.action
         if (gtdProperties.outcome) return gtdProperties.outcome

src/main/com/jdblabs/gtd/PropertyHelp.groovy

@@ -1,3 +1,8 @@
+/** 
+ * # PropertyHelp
+ * @author Jonathan Bernard (jdb@jdb-labs.com)
+ * @copyright 2013 [JDB Labs LLC](http://jdb-labs.com)
+ */
 package com.jdblabs.gtd
 
 import org.joda.time.DateMidnight
@@ -5,25 +10,51 @@ import org.joda.time.DateTime
 
 import java.text.SimpleDateFormat
 
+/**
+ * A poor man's serialization/deserialization library. Each Enum value
+ * represents a datatype that this class knows how to handle. The Enum entries
+ * consist of a regex to match data in textual form, a Class to match Java
+ * objects, a parse function to convert the textual form to a Java object, and
+ * a format function to convert a Java object to textual form.
+ * @org gtd.jdb-labs.com/PropertyHelp
+ */
 public enum PropertyHelp {
 
-    // Property types should be ordered here in order of decreasing specificity.
+    /// **Note:** Property types should be ordered here in order of decreasing
-    // That is, subclasses should come before the more general class so that
+    /// specificity. That is, subclasses should come before the more general
-    // objects are converted using the most specific class that
+    /// class so that objects are converted using the most specific class that
-    // PropertyHelp knows how to work with.
+    /// PropertyHelp knows how to work with.
+
+    /// #### `DATE_MIDNIGHT` ([`org.joda.time.DateMidnight`][joda-dm])
+    /// [joda-dm]: http://joda-time.sourceforge.net/apidocs/org/joda/time/DateMidnight.html
+    /// @example 2013-09-22
     DATE_MIDNIGHT(/^\d{4}-\d{2}-\d{2}$/, DateMidnight,
         { v -> DateMidnight.parse(v) },
         { d -> d.toString("YYYY-MM-dd") }),
+
+    /// #### `DATETIME` ([`org.joda.time.DateTime`][joda-dt])
+    /// [joda-dt]: http://joda-time.sourceforge.net/apidocs/org/joda/time/DateTime.html
+    /// @example 2013-09-22T13:42:57
     DATETIME(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/, DateTime,
         { v -> DateTime.parse(v) },
         { d -> d.toString("YYYY-MM-dd'T'HH:mm:ss") }),
-    // We never want to parse a value into a java.util.Date or
+
-    // java.util.Calendar object (we are using Joda Time instead of the
+    /// We never want to parse a value into a [`java.util.Date`][java-dt] or
-    // standard Java Date and Calendar objects) but we do want to be able to
+    /// [`java.util.Calendar`][java-cal] object (we are using Joda Time instead
-    // handle if someone gives us a Date or Calendar object. 
+    /// of the standard Java Date and Calendar objects) but we do want to be
+    /// able to handle if someone gives us a Date or Calendar object. 
+    /// 
+    /// [java-dt]: http://docs.oracle.com/javase/6/docs/api/java/util/Date.html
+    /// [java-cal]: http://docs.oracle.com/javase/6/docs/api/java/util/Calendar.html
+
+    /// #### `DATE` ([java.util.Date][java-dt])
+    /// [java-dt]: http://docs.oracle.com/javase/6/docs/api/java/util/Date.html
     DATE(NEVER_MATCH, Date,
         { v -> v }, // never called
         { d -> dateFormat.format(d) }),
+
+    /// #### `CALENDAR` ([`java.util.Calendar`][java-cal])
+    /// [java-cal]: http://docs.oracle.com/javase/6/docs/api/java/util/Calendar.html
     CALENDAR(NEVER_MATCH, Calendar,
         { v -> v }, // never called
         { c ->
@@ -31,15 +62,32 @@ public enum PropertyHelp {
             df.calendar = c
             df.format(c.time) }),
 
+    /// Similarly, we always parse integers into [`Long`][java-long] objects,
+    /// and floating point values into [`Double`][java-double] objects.
+    ///
+    /// [java-long]: http://docs.oracle.com/javase/6/docs/api/java/lang/Long.html
+    /// [java-double]: http://docs.oracle.com/javase/6/docs/api/java/lang/Double.html
+
+    /// #### `INTEGER` ([`java.lang.Integer`][java-int])
+    /// [java-int]: http://docs.oracle.com/javase/6/docs/api/java/lang/Integer.html
     INTEGER(NEVER_MATCH, Integer,
         { v -> v as Integer }, // never called
         { i -> i as String }),
+
+    /// #### `LONG` ([`java.lang.Long`][java-long])
+    /// [java-long]: http://docs.oracle.com/javase/6/docs/api/java/lang/Long.html
     LONG(/^\d+$/, Long,
         { v -> v as Long },
         { l -> l as String }),
+
+    /// #### `FLOAT` ([`java.lang.Float`][java-float])
+    /// [java-float]: http://docs.oracle.com/javase/6/docs/api/java/lang/Float.html
     FLOAT(NEVER_MATCH, Float,
         { v -> v as Float}, // never called
         { f -> f as String}),
+
+    /// #### `DOUBLE` ([`java.lang.Double`][java-double])
+    /// [java-double]: http://docs.oracle.com/javase/6/docs/api/java/lang/Double.html
     DOUBLE(/^\d+\.\d+$/, Double,
         { v -> v as Double },
         { d -> d as String });
@@ -51,11 +99,11 @@ public enum PropertyHelp {
     private static SimpleDateFormat dateFormat =
         new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
 
-    // This pattern for can never match (is uses negative lookahead to
+    /// This pattern for can never match (is uses negative lookahead to
-    // contradict itself).
+    /// contradict itself)
     private static String NEVER_MATCH = /(?!x)x/;
 
-
+    /// #### constructor
     public PropertyHelp(String pattern, Class klass, def parseFun,
     def formatFun) {
         this.pattern = pattern
@@ -63,19 +111,31 @@ public enum PropertyHelp {
         this.parseFun = parseFun
         this.formatFun = formatFun }
 
+    /// #### `matches`
+    /// Test if this Enum will match a given textual value.
     public boolean matches(String prop) { return prop ==~ pattern }
 
+    /// Test if this Enum will match a given Java Class.
     public boolean matches(Class klass) { return this.klass == klass }
 
+    /// #### `parse`
+    /// Try to parse a given textual value.
     public static Object parse(String value) {
-        def propertyType = PropertyHelp.values().find { 
+        /// Try to find a matching converter.
-            it.matches(value) }
+        def propertyType = PropertyHelp.values().find { it.matches(value) }
 
+        /// Use the converter to parse the value. If we did not find a
+        /// converter we assume this value is a plain string.
         return propertyType ? propertyType.parseFun(value) : value }
 
+    /// #### `format`
+    /// Try to format a given Java Object as a String.
     public static String format(def object) {
+        /// Try to find a converter that can handle this object type.
         def propertyType = PropertyHelp.values().find {
             it.klass.isInstance(object) }
 
+        /// Use the converter to format it as a string. If none was found we
+        /// use the object's `toString()` method.
         return propertyType ? propertyType.formatFun(object) : object.toString() }
 }

src/main/com/jdblabs/gtd/Util.groovy

@@ -1,9 +1,28 @@
+/** 
+ * # Util
+ * @author Jonathan Bernard (jdb@jdb-labs.com)
+ * @copyright 2013 [JDB Labs LLC](http://jdb-labs.com)
+ */
 package com.jdblabs.gtd
 
 import java.security.MessageDigest
 
+/**
+ * Utility methods common to this implementation of the Getting Things Done
+ * method. These methods provide support for working with a GTD repository
+ * which follows the organization and convention described 
+ * [here](jlp://gtd.jdb-labs.com/notes/organization-and-structure)
+ * @org gtd.jdb-labs.com/Util
+ */
 public class Util {
 
+    /** #### `findAllCopies`
+      * Given a GTD item file, find all files in the repository which are exact
+      * copies of this file (including thie file itself). This is useful when
+      * the same item exists in a project folder and in a next-action context
+      * folder.
+      *
+      * @org gtd.jdb-labs.com/Util/findAllCopies */
     public static List<File> findAllCopies(File original, File inDir) {
         MessageDigest md5 = MessageDigest.getInstance("MD5")
 
@@ -16,44 +35,79 @@ public class Util {
         
         return copies }
 
+    /** #### `inPath`
+      * Determine whether or not a given path is a subpath of a given parent
+      * path. This algorithm does not consider symlinks or hard links. It
+      * operates based on the textual path names. */
     public static boolean inPath(File parent, File child) {
         def parentPath = parent.canonicalPath.split("/")
         def childPath = child.canonicalPath.split("/")
 
-        // If the parent path is longer than the child path it cannot contain
+        /// If the parent path is longer than the child path it cannot contain
-        // the child path.
+        /// the child path.
         if (parentPath.length > childPath.length) return false;
 
-        // If the parent and child paths do not match at any point, the parent
+        /// If the parent and child paths do not match at any point, the parent
-        // path does not contain the child path.
+        /// path does not contain the child path.
         for (int i = 0; i < parentPath.length; i++)
             if (childPath[i] != parentPath[i])
                 return false;
 
-        // The parent path is at least as long as the child path, and the child
+        /// The parent path is at least as long as the child path, and the child
-        // path matches the parent path (up until the end of the parent path).
+        /// path matches the parent path (up until the end of the parent path).
-        // The child path either is the parent path or is contained by the
+        /// The child path either is the parent path or is contained by the
-        // parent path.
+        /// parent path.
         return true }
 
+    /** #### `getRelativePath`
+      * Given a parent path and a child path, assuming the child path is
+      * contained within the parent path, return the relative path from the
+      * parent to the child. */
     public static String getRelativePath(File parent, File child) {
         def parentPath = parent.canonicalPath.split("/")
         def childPath = child.canonicalPath.split("/")
 
+        /// If the parent path is longer it cannot contain the child path and
+        /// we cannot construct a relative path without backtracking.
         if (parentPath.length > childPath.length) return ""
 
+        /// Compare the parent and child path up until the end of the parent
+        /// path.
         int b = 0
         while (b < parentPath.length && parentPath[b] == childPath[b] ) b++;
 
+        /// If we stopped before reaching the end of the parent path it must be
+        /// that the paths do not match. The parent cannot contain the child and
+        /// we cannot build a relative path without backtracking.
         if (b != parentPath.length) return ""
         return (['.'] + childPath[b..<childPath.length]).join('/') }
 
+    /** #### `findGtdRootDir`
+      * Starting from a give directory, walk upwards through the file system
+      * heirarchy looking for the GTD root directory. The use case that
+      * motivates this function is when you are currently down in the GTD
+      * folder structure, in a context or project subfolder for example, and
+      * you need to find the root directory of the GTD structure, somewhere
+      * above you.
+      *
+      * This function returns a GTD Root Directory map, which has keys
+      * representing each of the top-level GTD directories, including a `root`
+      * key which corresponds to the parent file of these top-level GTD
+      * directories. The values are the File objects representing the
+      * directories. For example, if the GTD root is at `/home/user/gtd` then
+      * the root map (call it `m`) will have `m.projects ==
+      * File('/home/user/gtd/projects')`, `m.root == File('/home/user/gtd')`,
+      * etc.
+      * @org gtd.jdb-labs.com/notes/root-directory-map */
     public static Map findGtdRootDir(File givenDir) {
 
         def gtdDirs = [:]
 
+        /// Start by considering the current directory as a candidate.
         File currentDir = givenDir
         while (currentDir != null) {
+            /// We recognize the GTD root directory when it contains all of the
+            /// GTD top-level directories.
             gtdDirs = ["in", "incubate", "done", "next-actions", "projects",
                        "tickler", "waiting"].
                 collectEntries { [it, new File(currentDir, it)] }
@@ -62,7 +116,9 @@ public class Util {
                 gtdDirs.root = currentDir
                 return gtdDirs }
 
+            /// If this was not the GTD root, let's try the parent.
             currentDir = currentDir.parentFile }
 
+        /// If we never found the GTD root, we return an empty map.
         return [:] }
 }

src/main/com/jdblabs/gtd/cli/GTDCLI.groovy

@@ -1,3 +1,8 @@
+/** 
+ * # GTDCLI
+ * @author Jonathan Bernard (jdb@jdb-labs.com)
+ * @copyright 2013 [JDB Labs LLC](http://jdb-labs.com)
+ */
 package com.jdblabs.gtd.cli
 
 import com.jdblabs.gtd.Item
@@ -12,66 +17,109 @@ import org.joda.time.DateTime
 
 import static com.jdblabs.gtd.Util.*
 
+/**
+ * Command-line helper for working with this implementation of the Getting
+ * Things Done method. */
 public class GTDCLI {
 
     public static final String VERSION = "1.2"
     private static String EOL = System.getProperty("line.separator")
+
+    /// We have a persistent instance when we are in the context of a Nailgun
+    /// setup.
     private static GTDCLI nailgunInst
 
+    /// Used to wrap lines intelligently.
     private int terminalWidth
+
     private Scanner stdin
     private File workingDir
+
+    /// The [GTD Root Directory map][root-map] for our repository.
+    ///
+    /// [root-map]: jlp://gtd.jdb-labs.com/notes/root-directory-map
     private Map<String, File> gtdDirs
+
     //private Logger log = LoggerFactory.getLogger(getClass())
 
+    /** #### `main`
+      * Main entry point for a normal GTD CLI process. */
     public static void main(String[] args) {
+        /// Instantiate our GTDCLI instance using the configuration file at
+        /// `$HOME/.gtdclirc`.
         GTDCLI inst = new GTDCLI(new File(System.getProperty("user.home"),
             ".gtdclirc"))
 
+        /// Actual processing is done by the
+        /// [`run`](jlp://gtd.jdb-labs.com/GTDCLI/run) method
         if (args.length > 0) args[-1] = args[-1].trim()
         inst.run(args) }
 
+    /** #### `nailMain`
+      * Entry point for a GTD CLI process under [Nailgun][ng].
+      * [ng]: http://www.martiansoftware.com/nailgun/ */
     public static void nailMain(NGContext context) {
         if (nailgunInst == null)
             nailgunInst = new GTDCLI(new File(
                 System.getProperty("user.home"), ".gtdclirc"))
         else nailgunInst.stdin = new Scanner(context.in)
 
-        // trim the last argument, not all cli's are well-behaved
+        /// Trim the last argument; not all cli's are well-behaved
         if (context.args.length > 0) context.args[-1] = context.args[-1].trim()
 
         nailgunInst.run(context.args) }
 
+    /** #### `reconfigure`
+      * This method reloads the configuration before invoking the run function,
+      * allowing a long-lived instance to react to configuration changes. */
     public static void reconfigure(String[] args) {
+        /// If we do not have a long-running Nailgun instance we just call
+        /// main.
         if (nailgunInst == null) main(args)
         else {
+            /// Discard our old instance and instantiate a new one in order to
+            /// read afresh the configuration file.
             nailgunInst = null
             nailgunInst = new GTDCLI(new File(
                 System.getProperty("user.home"), ".gritterrc"))
 
             nailgunInst.run(args) } }
 
+    /** #### `constructor`
+      * Create a new GTDCLI instance, using the given configuration file. */
     public GTDCLI(File configFile) {
 
-        // parse the config file
+        /// Parse the groovy config file
         def config = [:]
         if (configFile.exists())
             config = new ConfigSlurper().parse(configFile.toURL())
 
-        // configure the terminal width
+        /// Configure the terminal width
         terminalWidth = (System.getenv().COLUMNS ?: config.terminalWidth ?: 79) as int
 
+        /// Configure our default working directory.
         workingDir = config.defaultDirectory ?
             new File(config.defaultDirectory) : 
             new File('.')
         
         stdin = new Scanner(System.in) }
 
+    /** #### `run`
+      * This method does the work of processing the user input and taking the
+      * appropriate action.
+      * @org gtd.jdb-labs.com/GTDCLI/run */
     protected void run(String[] args) {
         
+        /// Simple CLI options:
         def cliDefinition = [
+            /// -h, --help
+            /// :   Show the usage information.
             h: [longName: 'help'],
+            /// -d, --directory
+            /// :   Set the working directory for the CLI.
             d: [longName: 'directory', arguments: 1],
+            /// -v, --version
+            /// :   Print version information.
             v: [longName: 'version']]
 
         def opts = LightOptionParser.parseOptions(cliDefinition, args as List)
@@ -80,10 +128,17 @@ public class GTDCLI {
         if (opts.v) { println "GTD CLI v$VERSION"; return }
         if (opts.d) workingDir = new File(opts.d)
 
+        /// View the arguments as a [`LinkedList`][1] so we can use [`peek`][2]
+        /// and [`poll`][3].
+        ///
+        /// [1]: http://docs.oracle.com/javase/6/docs/api/java/util/LinkedList.html
+        /// [2]: http://docs.oracle.com/javase/6/docs/api/java/util/LinkedList.html#peek()
+        /// [3]: http://docs.oracle.com/javase/6/docs/api/java/util/LinkedList.html#poll()
         def parsedArgs = (opts.args as List) as LinkedList
 
         if (parsedArgs.size() < 1) printUsage()
 
+        /// Make sure we are in a GTD directory.
         gtdDirs = findGtdRootDir(workingDir)
         if (!gtdDirs) {
             println "fatal: '${workingDir.canonicalPath}'"
@@ -91,8 +146,10 @@ public class GTDCLI {
             return }
 
         while (parsedArgs.peek()) {
+            /// Pull off the first argument.
             def command = parsedArgs.poll()
 
+            /// Match the first argument and invoke the proper command method.
             switch (command.toLowerCase()) {
                 case ~/help/: printUsage(parsedArgs); break
                 case ~/done/: done(parsedArgs); break
@@ -106,6 +163,12 @@ public class GTDCLI {
                     println "Unrecognized command: ${command}"
                     break } } }
 
+    /** #### `process`
+      * Implement the *process* step of the GTD method. For details, see the
+      * [online help][help-process] included by running `gtd help process`
+      *
+      * [help-process]: jlp://gtd.jdb-labs.com/GTDCLI/help/process
+      */
     protected void process(LinkedList args) {
 
         def path = args.poll()
@@ -114,25 +177,25 @@ public class GTDCLI {
             if (!(gtdDirs = findGtdRootDir(givenDir))) {
                 println "'$path' is not a valid directory."; return }}
 
-        // Start processing items
+        /// Start processing items
         gtdDirs.in.listFiles().collect { new Item(it) }.each { item ->
 
             println ""
             def response
             def readline = {stdin.nextLine().trim()}
 
-            // 1. Is it actionable?
+            /// 1. Is it actionable?
             if (!item.title) item.title = filenameToString(item.file)
             response = prompt([">> $item", "Is it actionable?"]).toLowerCase()
             
-            // Not actionable
+            /// Not actionable, should we incubate this or trash it?
             if (!(response ==~ /yes|y/)) {
                 response = prompt("Incubate or trash?").toLowerCase()
 
-                // Trash
+                /// Trash
                 if ("trash" =~ response) item.file.delete()
 
-                // Incubate
+                /// Incubate
                 else {
                     println "Enter extra info. One 'key: value' pair per line."
                     println "(ex: date: YYYY-MM-DD, details)"
@@ -150,11 +213,11 @@ public class GTDCLI {
                     item.save()
                     oldFile.delete() }
 
-            // Actionable
+            /// It is actionable. Can we do it now in less than 2 minutes?
             } else {
                 response = prompt("Will it take less than 2 minutes?").toLowerCase()
 
-                // Do it now
+                /// Yes, so do it now.
                 if (response ==~ /yes|y/) {
                     println "Do it now."; print "> "
                     readline();
@@ -166,7 +229,7 @@ public class GTDCLI {
                     oldFile.delete()
                     return }
 
-                // > 2 minutes
+                /// It will take more than 2 minutes. Track it in our system.
                 item.outcome = prompt("What is the desired outcome?")
 
                 println "Enter extra info. One 'key: value' pair per line."
@@ -181,9 +244,10 @@ public class GTDCLI {
                         PropertyHelp.parse(parts[1].trim())
                     print "> " }
 
+                /// Does this need to be a separate project?
                 response = prompt("Too big for one action?").toLowerCase()
 
-                // Needs to be a project
+                /// Yes, this deserves it's own project folder.
                 if (response ==~ /yes|y/) {
                     def oldFile = item.file
                     item.file = new File(gtdDirs.projects,
@@ -192,12 +256,15 @@ public class GTDCLI {
                     oldFile.delete()
                     println "Moved to projects." }
 
-                // Is a single action
+                /// No, we can track this in one item. Is this something we
+                /// need someone else to do, should we defer it to our
+                /// next-actions list, or should we forget about it until a
+                /// future date?
                 else {
                     response = prompt("Delegate, defer, or tickler?").
                         toLowerCase()
 
-                    // Delegate
+                    /// Delegate, move to the *waiting* folder.
                     if (response =~ /del/) {
 
                         item.action = prompt([
@@ -212,7 +279,7 @@ public class GTDCLI {
                         println "Moved to ${gtdDirs.waiting.name} folder." }
 
 
-                    // Defer
+                    /// Defer, move to teh *next-actions* folder.
                     else if (response =~ /def/) {
                         item.action = prompt(["Next action.", ""])
 
@@ -225,7 +292,7 @@ public class GTDCLI {
                         println "Moved to the ${gtdDirs['next-actions'].name} folder."
                     }
 
-                    // Tickle
+                    /// Forget for now, move it to the *tickler* folder.
                     else {
                         item.action = prompt(["Next action.", ""])
                         item.tickle = prompt([
@@ -239,6 +306,13 @@ public class GTDCLI {
                         oldFile.delete()
                         println "Moved to the ${gtdDirs.tickler.name} folder." } } } } }
 
+    /** #### `done`
+      * Implement the `done` command to mark items as completed. For detailed
+      * information see the [online help][help-done] by running 
+      * `gtd help done`.
+      *
+      * [help-done]: jlp://gtd.jdb-labs.com/GTDCLI/help/done
+      */
     protected void done(LinkedList args) {
 
         def selectedFilePath = args.poll()
@@ -252,56 +326,68 @@ public class GTDCLI {
         if (selectedFile.isAbsolute()) item = new Item(selectedFile)
         else item = new Item(new File(workingDir, selectedFilePath))
 
-        // Move to the done folder.
+        /// Move to the done folder.
         def oldFile = item.file
         def date = new DateMidnight().toString("YYYY-MM-dd")
         item.file = new File(gtdDirs.done, "$date-${item.file.name}")
         item.save()
 
-        // Check if this item was in a project folder.
+        /// Check if this item was in a project folder.
         if (inPath(gtdDirs.projects, oldFile)) {
 
-            // Delete any copies of this item in the next actions folder.
+            /// Delete any copies of this item from the next actions folder.
             findAllCopies(oldFile, gtdDirs."next-actions").each { file ->
                 println "Deleting duplicate entry from the " +
                         "${file.parentFile.name} context."
                 file.delete() }
 
-            // Delete any copies of this item in the waiting folder.
+            /// Delete any copies of this item from the waiting folder.
             findAllCopies(oldFile, gtdDirs.waiting).each { file ->
                 println "Deleting duplicate entry from the " +
                     "${file.parentFile.name} waiting context."
                 file.delete() }}
 
-        // Check if this item was in the next-action or waiting folder.
+        /// Check if this item was in the next-action or waiting folder.
         if (inPath(gtdDirs["next-actions"], oldFile) ||
             inPath(gtdDirs.waiting, oldFile)) {
 
-            // Delete any copies of this item in the projects folder.
+            /// Delete any copies of this item from the projects folder.
             findAllCopies(oldFile, gtdDirs.projects).each { file ->
                 println "Deleting duplicate entry from the " +
                     "${file.parentFile.name} project."
                 file.delete() }}
 
-        // Delete the original
+        /// Delete the original
         oldFile.delete()
 
         println "'$item' marked as done." }
     
+    /** #### `calendar`
+      * Implement the `calendar` command to show all the items which are
+      * scheduled on the calendar. For detailed information see the
+      * [online help][help-calendar] by running `gtd help calendar`.
+      *
+      * [help-calendar]: jlp://gtd.jdb-labs.com/GTDCLI/help/calendar
+      */
     protected void calendar(LinkedList args) {
         def itemsOnCalendar = []
 
         MessageDigest md5 = MessageDigest.getInstance("MD5")
 
+        /// Temporary helper function to add GTD item files that have the
+        /// `date` property defined.
         def addCalendarItems = { file ->
             if (!file.isFile()) return
             def item = new Item(file)
             if (item.date) itemsOnCalendar << item }
 
+        /// Look through each of the `next-actions`, `waiting`, and `projects`
+        /// folders for items which should be on the calendar
         gtdDirs."next-actions".eachFileRecurse(addCalendarItems)
         gtdDirs.waiting.eachFileRecurse(addCalendarItems)
         gtdDirs.projects.eachFileRecurse(addCalendarItems)
 
+        /// De-duplicate the list.
         itemsOnCalendar = itemsOnCalendar.unique { md5.digest(it.file.bytes) }.
                                           sort { it.date }
 
@@ -309,6 +395,7 @@ public class GTDCLI {
 
         def currentDate = null
             
+        /// Print each day of items.
         itemsOnCalendar.each { item ->
             def itemDay = new DateMidnight(item.date)
             if (itemDay != currentDate) {
@@ -319,9 +406,17 @@ public class GTDCLI {
 
             println "  $item" } }
 
+    /** #### `listCopies`
+      * Implement the `list-copies` command to show all the copies of a given
+      * item in the repository. For detailed information see the
+      * [online help][help-list-copies] by running `gtd help list-copies`.
+      *
+      * [help-list-copies]: jlp://gtd.jdb-labs.com/GTDCLI/help/list-copies
+      */
     protected void listCopies(LinkedList args) {
 
         args.each { filePath ->
+            /// First find the file they have named.
             def file = new File(filePath)
 
             if (!file.isAbsolute()) file = new File(workingDir, filePath)
@@ -334,6 +429,9 @@ public class GTDCLI {
             println "Copies of $originalRelativePath:"
             println ""
 
+            /// Find all copies using [`Util.findAllCopies`][1] and print their
+            /// relative paths.
+            /// [1]: jlp://gtd.jdb-labs.com/Util/findAllCopies
             findAllCopies(file, gtdDirs.root).each { copy ->
                 if (copy.canonicalPath != file.canonicalPath) {
                     String relativePath = getRelativePath(gtdDirs.root, copy)
@@ -341,8 +439,16 @@ public class GTDCLI {
 
         args.clear() }
 
+    /** #### `new`
+      * Implement the `new` command to create a new GTD item in the current
+      * directory. For detailed information see the [online help][help-new] by
+      * running `gtd help new`.
+      *
+      * [help-new]: jlp://gtd.jdb-labs.com/GTDCLI/help/new
+      */
     protected void newAction(LinkedList args) {
 
+        /// Get the next action.
         def response = prompt(["Next action?", ""])
         def file = new File(workingDir, stringToFilename(response))
         file.createNewFile()
@@ -355,8 +461,14 @@ public class GTDCLI {
         println "End with an empty line."
         print "> "
 
+        /// Read in item properties.
         while (response = stdin.nextLine().trim()) {
+            /// Skip lines that do not contain either `:` or `=` (the key-value
+            /// delimiters).
             if (!(response =~ /[:=]/)) continue
+
+            /// Split the line into key and value and add this property to the
+            /// item.
             def parts = response.split(/[:=]/)
             item[parts[0].trim().toLowerCase()] =
                 PropertyHelp.parse(parts[1].trim())
@@ -364,14 +476,22 @@ public class GTDCLI {
 
         item.save() }
 
+    /** #### `tickler`
+      * Implement the `tickler` command to move items in the *tickler* folder to
+      * the *next-actions* folder if their time has come. For detailed
+      * information see the [online help][help-tickler] by running
+      * `gtd help tickler`.
+      *
+      * [help-tickler]: jlp://gtd.jdb-labs.com/GTDCLI/help/tickler
+      */
     protected void tickler(LinkedList args) {
 
         gtdDirs.tickler.eachFileRecurse { file ->
             def item = new Item(file)
             def today = new DateMidnight()
 
-            // If the item is scheduled to be tickled today (or in the past)
+            /// If the item is scheduled to be tickled today (or in the past)
-            // then move it into the next-actions folder
+            /// then move it into the next-actions folder
             if ((item.tickle as DateMidnight) <= today) {
                 println "Moving '${item.action}' out of the tickler."
                 def oldFile = item.file
@@ -381,10 +501,20 @@ public class GTDCLI {
                 item.save()
                 oldFile.delete() }}}
 
+    /** #### `ls`
+      * Implement the `ls` command to pretty print all items in a context
+      * folder, a project folder, or the *next-action* folder. For detailed
+      * information see the [online help][help-ls] by running
+      * `gtd help ls`.
+      *
+      * [help-ls]: jlp://gtd.jdb-labs.com/GTDCLI/help/ls
+      */
     protected void ls(LinkedList args) {
 
         def target = args.poll()
 
+        /// Temporary helper function to print all the items in a given
+        /// directory.
         def printItems = { dir ->
             if (!dir.exists() || !dir.isDirectory()) return
             println "-- ${getRelativePath(gtdDirs.root, dir)} --"
@@ -397,20 +527,25 @@ public class GTDCLI {
 
             println "" }
 
-        // If we have a named context or project, look for those items
+        /// If we have a named context or project, look for those items
-        // specifically
+        /// specifically
         if (target) {
 
             printItems(new File(gtdDirs['next-actions'], target))
             printItems(new File(gtdDirs.waiting, target))
             printItems(new File(gtdDirs.projects, target)) }
 
+        /// Otherwise print all items in the *next-actions* and *waiting*
+        /// folders and all their subfolders.
         else {
             printItems(gtdDirs['next-actions'])
             printItems(gtdDirs['waiting'])
             gtdDirs['next-actions'].eachDir(printItems)
             gtdDirs['waiting'].eachDir(printItems) } }
 
+    /** #### `help`
+      * Implement the `help` command which provides the online-help. Users can
+      * access the online help for a command by running `gtd help <command>`.*/
     protected void printUsage(LinkedList args) {
 
         if (!args) {
@@ -445,6 +580,8 @@ top-level commands:
             def command = args.poll()
 
             switch(command.toLowerCase()) {
+                /// Online help for the `process` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/process
                 case ~/process/: println """\
 usage: gtd process
 
@@ -475,6 +612,8 @@ and guides you through the *process* step of the GTD method as follows:
               directory                              directory."""
                     break
 
+                /// Online help for the `done` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/done
                 case ~/done/: println """\
 usage: gtd done <action-file>
 
@@ -493,9 +632,11 @@ project folders into next action or waiting contexts, so you can keep a view of
 the item organized by the project or in your next actions list. The GTD CLI tool
 is smart enough to recognize that these are the same items filed in more than
 one place and deal with them all in one fell swoop. Duplicates are determined by
-exact file contents (MD5 has of the file contents)."""
+exact file contents (MD5 hash of the file contents)."""
                     break
 
+                /// Online help for the `calendar` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/calendar
                 case ~/calendar/: println """\
 usage: gtd calendar
 
@@ -505,6 +646,8 @@ Remember that in the GTD calendar items are supposed to be hard dates, IE.
 things that *must* be done on the assigned date."""
                     break
 
+                /// Online help for the `list-copies` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/list-copies
                 case ~/list-copies/: println """\
 usage: gtd list-copies <action-file>
 
@@ -515,6 +658,8 @@ This command searched through the current GTD repository for any items that are
 duplicates of this item."""
                     break
 
+                /// Online help for the `new` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/new
                 case ~/new/: println """\
 usage: gtd new
 
@@ -524,6 +669,8 @@ that should be associated with it, then creates the action file in the current
 directory."""
                     break
 
+                /// Online help for the `tickler` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/tickler
                 case ~/tickler/: println """\
 usage: gtd tickler
 
@@ -532,6 +679,8 @@ file for any items that should become active (based on their <tickle> property)
 and moves them out of the tickler file and into the next-actions file."""
                     break
 
+                /// Online help for the `ls`/`list-context` command.
+                /// @org gtd.jdb-labs.com/GTDCLI/help/ls
                 case ~/ls|list-context/: println """\
 usage gtd ls [<context> ...]
 
@@ -543,6 +692,9 @@ context or project is named, all contexts are listed."""
         }
     }
 
+    /** #### `prompt`
+      * Prompt the user for an answer to a question. This is a helper to loop
+      * until the user has entered an actual response.  */
     protected String prompt(def msg) {
         if (msg instanceof List) msg = msg.join(EOL)
         msg += "> "
@@ -553,9 +705,14 @@ context or project is named, all contexts are listed."""
         
         return line }
 
+    /** #### `filenameToString`
+      * The default pretty-print conversion for filenames. */
     public static String filenameToString(File f) {
         return f.name.replaceAll(/[-_]/, " ").capitalize() }
 
+    /** #### `stringToFilename`
+      * Helper method to convert a user-entered string into something more
+      * palatable for a filename. */
     public static String stringToFilename(String s) {
         return s.replaceAll(/\s/, '-').
                 replaceAll(/[';:(\.$)]/, '').

src/main/com/jdblabs/gtd/servlet/GTDServlet.groovy

@@ -1,3 +1,8 @@
+/** 
+ * # GTDServlet
+ * @author Jonathan Bernard (jdb@jdb-labs.com)
+ * @copyright 2013 [JDB Labs LLC](http://jdb-labs.com)
+ */
 package com.jdblabs.gtd.servlet
 
 import com.jdblabs.gtd.Item
@@ -17,23 +22,44 @@ import javax.servlet.http.HttpSession
 
 import static javax.servlet.http.HttpServletResponse.*
 
+/**
+ * Servlet to expose a GTD file-based repository over HTTP via a REST API.
+ */
 public class GTDServlet extends HttpServlet {
 
     protected Map gtdDirs
     private SmartConfig config
 
+    /** ### TempRequestData
+      * Helper class to encapsulate data shared by several methods while
+      * fulfilling a single request.
+      *
+      * @org gtd.jdb-labs.com/GTDServlet/TempRequestData */
     private class TempRequestData {
         public String username
         public def defaultPermissions
     }
 
+    /** #### `init`
+      * Overrides [`GenericServlet.init(ServletConfig)`][1] to configure
+      * this servlet instance. Primarily we need to find our GTD root directory
+      * and read the `.properties` configuration file from the GTD root
+      * directory.
+      *
+      * [1]: http://docs.oracle.com/javaee/6/api/javax/servlet/GenericServlet.html#init(javax.servlet.ServletConfig) */
     void init(ServletConfig config) {
+
+        /// We exepect the path to the GTD root directory to be supplied in the
+        /// servlet configuration: typically in the `web.xml` file.
         String gtdDirName = config.getInitParameter("gtdRootDir")
         this.gtdDirs = Util.findGtdRootDir(new File(gtdDirName))
         if (!gtdDirs) throw new ServletException(
             "Unable to initialize GTD servlet: no GTD root dir found in the " +
             "configured path (${gtdDirName}).")
             
+        /// We expect to find a `.properties` file in the root directory that
+        /// we will use to configure the servlet for this repository (primarily
+        /// users and permissions).
         def cfgFile = new File(gtdDirs.root, '.properties')
         if (!cfgFile.isFile() || !cfgFile.exists()) throw new ServletException(
             "Unable to find the GTD/.properties configuration file. " +
@@ -41,12 +67,26 @@ public class GTDServlet extends HttpServlet {
 
         this.config = new SmartConfig(cfgFile) }
 
+    /** #### `doOptions`
+      * Overrides [`HttpServlet.doOptions`][2] as we need to include
+      * [CORS headers][3] in response to a [CORS pre-flight request][4].
+      *
+      * [2]: http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServlet.html#doOptions(javax.servlet.http.HttpServletRequest,%20javax.servlet.http.HttpServletResponse)
+      * [3]: https://developer.mozilla.org/en-US/docs/HTTP/Access_control_CORS#The_HTTP_response_headers
+      * [4]: https://developer.mozilla.org/en-US/docs/HTTP/Access_control_CORS#Preflighted_requests
+      */
     void doOptions(HttpServletRequest request, HttpServletResponse response) {
+        /// A browser will not send credentials like session cookies unless the
+        /// server responds with the exact Origin from the request header, so
+        /// we will use the Origin header unless the client did not send this
+        /// header.
         response.addHeader("Access-Control-Allow-Origin",
             request.getHeader("Origin") ?: "*")
         response.addHeader("Access-Control-Allow-Credentials", "true")
         response.status = SC_OK
         
+        /// We will set the `Access-Control-Allow-Methods` header based on the
+        /// endpoint that the client is trying to reach.
         switch (request.servletPath) {
             case '/login':
                 response.addHeader("Allow", "POST")
@@ -62,34 +102,44 @@ public class GTDServlet extends HttpServlet {
                 response.status = SC_NOT_FOUND }
     }
 
+    /** #### `doPost`
+      * Override the [`HttpServlet.doPost`][5] method to provide responses to
+      * `POST` requests.
+      *
+      * [5]: http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServlet.html#doPost(javax.servlet.http.HttpServletRequest,%20javax.servlet.http.HttpServletResponse) */
     void doPost(HttpServletRequest request, HttpServletResponse response) {
+        /// All our responses use JSON-formatted data.
         response.addHeader("Content-Type", "application/json")
+
+        /// Add the CORS headers>
         response.addHeader("Access-Control-Allow-Origin",
             request.getHeader("Origin") ?: "*")
         response.addHeader("Access-Control-Allow-Credentials", "true")
 
+        /// Get this user's session
         HttpSession session = request.getSession(true);
 
-        // If the user is posting to /gtd/login then let's try to authenticate
+        /// If the user is posting to `/gtd/login` then let's try to
-        // them.
+        /// authenticate them. We don't care about the state of the existing
+        /// session.
         if (request.servletPath == '/login') {
-            // Parse the username/password from the request.
+            /// Parse the username/password from the request.
             def requestBody
             try { requestBody = new JsonSlurper().parse(request.reader) }
             catch (JsonException jsone) {
                 response.status = SC_BAD_REQUEST
                 return }
 
-            // Build our list of known users.
+            /// Build our list of known users.
             def users = config.accountNames.split(/,/).collect { it.trim() }
 
-            // Lookup the user's password in the configuration (will be null if
+            /// Lookup the user's password in the configuration (will be null if
-            // we are given an invalid username).
+            /// we are given an invalid username).
             String expectedPwd = config."account.${requestBody.username}.password"
 
-            // Reject the login request if the user is not defined by our
+            /// Reject the login request if the user is not defined by our
-            // configuration. Note: timing attack possible due to string
+            /// configuration. Note: timing attack possible due to string
-            // comparison.
+            /// comparison.
             if (!users.contains(requestBody.username) ||
                  requestBody.password != expectedPwd) {
                 response.status = SC_UNAUTHORIZED
@@ -102,13 +152,13 @@ public class GTDServlet extends HttpServlet {
             writeJSON([status: "ok"], response)
             return }
 
-        // If the user is not authenticated return a 401 Unauthorized.
+        /// If the user is not authenticated return a `401 Unauthorized`.
         else if (!((boolean)session.getAttribute('authenticated'))) {
             response.status = SC_UNAUTHORIZED
             return }
 
-        // Right now there is no other endpoint that supports POST, so return
+        /// Right now there is no other endpoint that supports `POST`, so return
-        // 404 Not Found or 405 Method Not Allowed
+        /// `404 Not Found` or `405 Method Not Allowed`
         switch (request.servletPath) {
             case ~/\/gtd\/contexts.*/: 
             case ~/\/gtd\/projects.*/: 
@@ -120,66 +170,75 @@ public class GTDServlet extends HttpServlet {
         }
     }
 
+    /** #### `doGet`
+      * Overrides the [`HttpServlet.doGet`][6] method to provide reponses to
+      * `GET` requests.
+      *
+      * [6]: http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServlet.html#doGet(javax.servlet.http.HttpServletRequest,%20javax.servlet.http.HttpServletResponse) */
     void doGet(HttpServletRequest request, HttpServletResponse response) {
 
         response.status = SC_OK
+
+        /// All of our responses have JSON formatted content.
         response.addHeader("Content-Type", "application/json")
+
+        /// Add CORS headers.
         response.addHeader("Access-Control-Allow-Origin",
             request.getHeader("Origin") ?: "*")
         response.addHeader("Access-Control-Allow-Credentials", "true")
 
         HttpSession session = request.getSession(true);
 
-        // If the user is not authenticated return 401 Unauthorized.
+        /// If the user is not authenticated return `401 Unauthorized`.
         if (!((boolean)session.getAttribute('authenticated'))) {
             response.status = SC_UNAUTHORIZED
             return }
 
         def curData = new TempRequestData()
 
-        // Read the username from the session object.
+        /// Read the username from the session object.
         curData.username = session.getAttribute('username')
 
-        // Determine the user's default permissions.
+        /// Determine the user's default permissions.
         curData.defaultPermissions =
             (config."account.${curData.username}.defaultPermissions" ?: "")
             .split(/,/).collect { it.trim() }
 
         switch(request.servletPath) {
 
-            // If they are invoking /gtd/logout then invalidate their session
+            /// If they are invoking `/gtd/logout` then invalidate their session
-            // and return 200 OK
+            /// and return `200 OK`
             case "/logout":
                 session.removeAttribute("authenticated")
                 session.invalidate()
                 break
 
-            // If they are GET'ing /gtd/contexts then return the list of
+            /// ##### `/gtd/contexts`
-            // contexts that are readable by this user.
+            /// Return the list of contexts that are readable by this user.
             case "/contexts":
 
-                // Filter the directories to find the ones that the user has
+                /// Filter all the context directories to find the ones that
-                // read access to.
+                /// the user has read access to.
                 def selectedContexts = findAllowedDirs("read", curData,
                     gtdDirs['next-actions'].listFiles())
 
+                /// Now format our response as JSON and write it to the response
                 def returnData = selectedContexts.collect { entry ->
                     [id: entry.dir.name, title: entry.props.title] }
 
-                // Now format our response as JSON and write it to the response
                 writeJSON(returnData, response)
                 break
 
-            // If they are GET'ing /gtd/contexts/<contextId> then return data
+            /// ##### `/gtd/contexts/<contextId>`
-            // for the requested context, assuming it is readable for this
+            /// Return data for the requested context, assuming it is
-            // user.
+            /// readable for this user.
             case ~'/contexts/(.+)':
                 String contextId = Matcher.lastMatcher[0][1]
 
-                // Try to find the named context.
+                /// Try to find the named context.
                 File ctxDir = new File(gtdDirs['next-actions'], contextId)
 
-                // Check that they have read permission on this directory.
+                /// Check that they have read permission on this directory.
                 def filteredList = findAllowedDirs("read", curData, [ctxDir])
                 if (filteredList.size() == 0) {
                     response.status = SC_NOT_FOUND
@@ -191,11 +250,11 @@ public class GTDServlet extends HttpServlet {
                 writeJSON(returnData, response)
                 break
 
-            // If they are GET'ing /gtd/projects then return the list of
+            /// ##### `/gtd/projects`
-            // projects that are readable for this user.
+            /// Return the list of projects that are readable for this user.
             case "/projects":
-                // Filter the directories to find the ones that the user has
+                /// Filter the project directories to find the ones that the
-                // read access to.
+                /// user has read access to.
                 def selectedProjects = findAllowedDirs("read", curData,
                     gtdDirs['projects'].listFiles())
 
@@ -204,74 +263,81 @@ public class GTDServlet extends HttpServlet {
                 writeJSON(returnData, response)
                 break
 
-            // If they are GET'ing /gtd/projects/<projectId> then return the
+            /// ##### `/gtd/projects/<projectId>`
-            // list of projects that are readable for this user.
+            /// Return data for the requested project, assuming it is readable
+            /// for this user.
             case ~'/projects/(.+)':
                 String projectId = Matcher.lastMatcher[0][1]
 
-                // Try to find the named project.
+                /// Try to find the named project.
                 File projectDir = new File(gtdDirs['projects'], contextId)
 
-                // Check that they have read permission on this directory.
+                /// Check that they have read permission on this directory.
                 def filteredList = findAllowedDirs("read", curData, [projectDir])
                 if (filteredList.size() == 0) {
                     response.status = SC_NOT_FOUND
                     writeJSON([status: "not found"], response)
                     break }
 
+                /// Format as JSON and return.
                 def entry = filteredList[0]
                 def returnData = [id: entry.dir.name, title: entry.props.title]
                 writeJSON(returnData, response)
                 break
 
+            /// ##### `/gtd/next-actions/<contexts-and-projects>`
+            /// Return all of the items contained in the named contexts and
+            /// projects, assuming the user has access to them.
+            /// `<contexts-and-projects>` is expected to be a comma-delimited
+            /// list of context and project IDs.
             case ~'/next-actions/(.+)':
-                // Parse out the list of contexts/projects
+                /// Parse out the list of contexts/projects
                 List ids = Matcher.lastMatcher[0][1].split(/,/) as List
 
                 List searchDirs = []
 
-                // Look for each id in our list of contexts
+                /// Look for each id in our list of contexts
                 searchDirs.addAll(ids.collect { id ->
                     new File(gtdDirs['next-actions'], id) })
 
-                // And look for each id in our list of projects
+                /// And look for each id in our list of projects
                 searchDirs.addAll(ids.collect { id ->
                     new File(gtdDirs['projects'], id) })
 
-                // Filter the directories to find the ones that exist and are
+                /// Filter the directories to find the ones that exist and are
-                // readable by our user.
+                /// readable by our user.
                 def actualDirs = findAllowedDirs("read", curData, searchDirs)
 
-                // Collect all the items.
+                /// Collect all the items.
                 def items = [], itemFiles = [], uniqueItemFiles = []
 
-                // Collect all the items across all the actual directories.
+                /// Collect all the items across all the actual directories.
                 itemFiles = actualDirs.collectMany { entry ->
                     entry.dir.listFiles({ f -> !f.isHidden() } as FileFilter) as List }
 
-                // De-duplicate the items using the GTD findAllCopies utility
+                /// De-duplicate the items using the [`Util.findAllCopies`][8]
-                // method to remove items that are listed in a chosen context
+                /// method to remove items that are listed in a chosen context
-                // and project. We are going to do this by identifying
+                /// and project. We are going to do this by identifying
-                // duplicate items, removing all of them from the itemFiles
+                /// duplicate items, removing all of them from the itemFiles
-                // list and adding only the first to our new uniqueItemFiles
+                /// list and adding only the first to our new uniqueItemFiles
-                // list.
+                /// list.
+                ///
+                /// [8]: jlp://gtd.jdb-labs.com/Util/findAllCopies
                 while (itemFiles.size() > 0) {
                     def item = itemFiles.remove(0)
-
-                    // Find all duplicates.
                     def dupes = Util.findAllCopies(item, gtdDirs.root)
 
-                    // Remove them from the source collection.
+                    /// Remove them from the source collection.
                     itemFiles.removeAll { f1 -> dupes.any { f2 ->
                         f1.canonicalPath == f2.canonicalPath }}
 
-                    // Add the first one to the destination collection.
+                    /// Add the first one to the destination collection.
                     uniqueItemFiles << item }
 
-                // Create Item objects for each item.
+                /// Create Item objects for each item.
                 items = uniqueItemFiles.collect { new Item(it) }
 
-                // Return all the items.
+                /// Return all the items.
                 def returnData = items.collect { item ->
                     def m = [id: item.file.name]
                     item.gtdProperties.each { k, v ->
@@ -281,7 +347,7 @@ public class GTDServlet extends HttpServlet {
                 writeJSON(returnData, response)
                 break
 
-            // Otherwise return a 404 Not Found
+            /// Otherwise return a `404 Not Found`
             default:
                 response.status = SC_NOT_FOUND
                 break
@@ -290,6 +356,15 @@ public class GTDServlet extends HttpServlet {
         response.writer.flush()
     }
 
+    /** #### `findAllowedDirs`
+      * Helper method to take a permission or list of permissions, a list of
+      * File objects and return the subset of File objects which represent
+      * existing directories for which the current user has all of the
+      * requested permissions. This method also takes a [TempRequestData][7]
+      * object which provides access to the username and default permissions
+      * for the user making the request.
+      *
+      * [7]: jlp://gtd.jdb-labs.com/GTDServlet/TempRequestData */
     protected Collection findAllowedDirs(String permission,
     TempRequestData curData, def dirs) {
         return findAllowedDirs([permission], curData, dirs) }
@@ -298,39 +373,43 @@ public class GTDServlet extends HttpServlet {
     TempRequestData curData, def dirs) {
         return dirs.collectMany { dir ->
 
-            println ">> Considering ${dir.canonicalPath}"
+            /// Only directories can be contexts and projects.
-
-            // Only directories can be contexts and projects.
             if (!dir.exists() || !dir.isDirectory()) { return [] }
 
-            // Check for a .properties file in this directory.
+            /// Check for a .properties file in this directory.
             def propFile = new File(dir, '.properties')
 
-            // If it does not exist, defer to the defaults.
+            /// If it does not exist, defer to the defaults.
             if (!propFile.exists() &&
                 !curData.defaultPermissions.containsAll(requiredPermissions)) {
                 return [] }
             
-            // Look for the account.<curData.username>.Permissions property.
+            /// Look for the `account.<curData.username>.permissions` property.
+            /// *Note* that the property access on `itemProps` will write the
+            /// default value to the properties file if it does not exist. This
+            /// may result in a new properties file being created.
             def itemProps = new SmartConfig(propFile)
             def actualPermissions = itemProps.getProperty(
                 "account.${curData.username}.permissions", "default").
                 split(/,/).collect { it.trim() }
 
-            // If the user has the correct permission on this context, or
+            /// If the user has the correct permission on this context, or
-            // if this context inherits their default permissions, and
+            /// if this context inherits their default permissions, and
-            // they have the correct permission by default, then we show
+            /// they have the correct permission by default, then we allow
-            // this context. If this is not the case (tested in the
+            /// this context. If this is not the case (tested in the
-            // following conditional) we do not show this context.
+            /// following conditional) we do not allow this context.
             if (!actualPermissions.containsAll(requiredPermissions) &&
                 !(actualPermissions.containsAll('default') &&
                   curData.defaultPermissions.containsAll(requiredPermissions))) {
                 return [] }
 
-            // At this point we know the context exists, and the user
+            /// At this point we know the context exists, and the user
-            // has permission to read it.
+            /// has permission to access it.
             return [[ dir: dir, props: itemProps ]] } }
 
+    /** #### `writeJSON`
+      * Helper method to write an object as JSON to the response. Mainly used
+      * to increase readability. */
     protected void writeJSON(def data, def response) {
         new JsonBuilder(data).writeTo(response.writer) }
 }