From 9f419891d1bdc109c3a487083b5a15ddaef2f7c7 Mon Sep 17 00:00:00 2001
From: Paul Duncan <pabs@pablotron.org>
Date: Thu, 6 Sep 2018 22:27:11 -0400
Subject: java: add Template documentation

---
 .../main/java/org/pablotron/luigi/Template.java    | 101 ++++++++++++++++++++-
 1 file changed, 98 insertions(+), 3 deletions(-)

(limited to 'java/src')

diff --git a/java/src/main/java/org/pablotron/luigi/Template.java b/java/src/main/java/org/pablotron/luigi/Template.java
index 8ce8793..af3e49b 100644
--- a/java/src/main/java/org/pablotron/luigi/Template.java
+++ b/java/src/main/java/org/pablotron/luigi/Template.java
@@ -4,15 +4,28 @@ import java.util.Map;
 import org.pablotron.luigi.Parser;
 import org.pablotron.luigi.Filter;
 import org.pablotron.luigi.errors.LuigiError;
+import org.pablotron.luigi.errors.LuigiError;
 import org.pablotron.luigi.actions.Action;
 
+/**
+ * Template class.
+ */
 public final class Template {
-  private static final String VERSION = "0.4.0";
+  /**
+   * Luigi template version.
+   */
+  public static final String VERSION = "0.4.0";
 
   private final String template;
   private final Action actions[];
   private final Map<String, Filter.Handler> filters;
 
+  /**
+   * Create a new template with the given string and filter set.
+   *
+   * @param template Template string.
+   * @param filters Map of filter names to filter handlers.
+   */
   public Template(
     final String template,
     final Map<String, Filter.Handler> filters
@@ -22,10 +35,26 @@ public final class Template {
     this.actions = Parser.parse_template(template);
   }
 
+  /**
+   * Create a new template with the given string and the default filter
+   * set.
+   *
+   * @param template Template string.
+   */
   public Template(final String template) throws LuigiError {
     this(template, Filter.FILTERS);
   }
 
+  /**
+   * Run this template with given arguments, then return the result as a
+   * String.
+   *
+   * @param args Template arguments.
+   *
+   * @throws UnknownKeyError If a key specified in the template does not exist.
+   * @throws UnknownFilterError If a filter specified in the template does not exist.
+   * @throws FilterError If a given filter fails.
+   */
   public String run(final Map<String, String> args) throws LuigiError {
     final StringBuilder r = new StringBuilder();
 
@@ -35,6 +64,17 @@ public final class Template {
     return r.toString();
   }
 
+  /**
+   * Run this template with given arguments, and pass each result chunks
+   * to the given result handler.
+   *
+   * @param args Template arguments.
+   * @param rh Result handler.
+   *
+   * @throws UnknownKeyError If a key specified in the template does not exist.
+   * @throws UnknownFilterError If a filter specified in the template does not exist.
+   * @throws FilterError If a given filter fails.
+   */
   public void run(
     final Map<String, String> args,
     final ResultHandler r
@@ -44,10 +84,26 @@ public final class Template {
     }
   }
 
+  /**
+   * Return the original template string for this Template instance.
+   */
   public String toString() {
     return this.template;
   }
 
+  /**
+   * Create and run template with given arguments, using the default
+   * filter set, then return the result as a String.
+   *
+   * @param template Template string.
+   * @param args Template arguments.
+   *
+   * @return Template expansion result.
+   *
+   * @throws UnknownKeyError If a key specified in the template does not exist.
+   * @throws UnknownFilterError If a filter specified in the template does not exist.
+   * @throws FilterError If a given filter fails.
+   */
   public static String run(
     final String template,
     final Map<String, String> args
@@ -55,14 +111,40 @@ public final class Template {
     return Template.run(template, args, Filter.FILTERS);
   }
 
+  /**
+   * Create and run template with given arguments and result handler,
+   * using the default filter set.
+   *
+   * @param template Template string.
+   * @param args Template arguments.
+   * @param rh Result handler that result chunks are passed to.
+   *
+   * @throws UnknownKeyError If a key specified in the template does not exist.
+   * @throws UnknownFilterError If a filter specified in the template does not exist.
+   * @throws FilterError If a given filter fails.
+   */
   public static void run(
     final String template,
     final Map<String, String> args,
-    final ResultHandler r
+    final ResultHandler rh
   ) throws LuigiError {
-    run(template, args, Filter.FILTERS, r);
+    run(template, args, Filter.FILTERS, rh);
   }
 
+  /**
+   * Create and run template with given arguments, and filters, then
+   * return the result as a String.
+   *
+   * @param template Template string.
+   * @param args Template arguments.
+   * @param filters Template filters.
+   *
+   * @return Template expansion result.
+   *
+   * @throws UnknownKeyError If a key specified in the template does not exist.
+   * @throws UnknownFilterError If a filter specified in the template does not exist.
+   * @throws FilterError If a given filter fails.
+   */
   public static String run(
     final String template,
     final Map<String, String> args,
@@ -72,6 +154,19 @@ public final class Template {
     return t.run(args);
   }
 
+  /**
+   * Create and run template with given arguments, filters, and result
+   * handler.
+   *
+   * @param template Template string.
+   * @param args Template arguments.
+   * @param filters Template filters.
+   * @param rh Result handler that result chunks are passed to.
+   *
+   * @throws UnknownKeyError If a key specified in the template does not exist.
+   * @throws UnknownFilterError If a filter specified in the template does not exist.
+   * @throws FilterError If a given filter fails.
+   */
   public static void run(
     final String template,
     final Map<String, String> args,
-- 
cgit v1.2.3