From 163e6cf03d369f0b062c8aa19fb26c5892bc2b05 Mon Sep 17 00:00:00 2001
From: Paul Duncan <pabs@pablotron.org>
Date: Thu, 6 Sep 2018 23:02:52 -0400
Subject: java: document actions

---
 .../java/org/pablotron/luigi/actions/Action.java   | 16 +++++++++++-
 .../org/pablotron/luigi/actions/FilterAction.java  | 29 +++++++++++++++++++++-
 .../org/pablotron/luigi/actions/TextAction.java    | 22 ++++++++++++++++
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/java/src/main/java/org/pablotron/luigi/actions/Action.java b/java/src/main/java/org/pablotron/luigi/actions/Action.java
index a473f62..0b1fb6b 100644
--- a/java/src/main/java/org/pablotron/luigi/actions/Action.java
+++ b/java/src/main/java/org/pablotron/luigi/actions/Action.java
@@ -1,12 +1,26 @@
 package org.pablotron.luigi.actions;
 
 import java.util.Map;
+
 import org.pablotron.luigi.Filter;
 import org.pablotron.luigi.errors.LuigiError;
 
+/**
+ * Parser action.
+ */
 public interface Action {
+  /**
+   * Called during template run to expand given action.
+   *
+   * @param filters Template filters.
+   * @param filters Run argument map.
+   *
+   * @return Action result.
+   *
+   * @throws LuigiError If an error occurs while running this action.
+   */
   public String run(
-    Map<String, Filter.Handler> filters, 
+    Map<String, Filter.Handler> filters,
     Map<String, String> args
   ) throws LuigiError;
 };
diff --git a/java/src/main/java/org/pablotron/luigi/actions/FilterAction.java b/java/src/main/java/org/pablotron/luigi/actions/FilterAction.java
index 091a285..39fd48c 100644
--- a/java/src/main/java/org/pablotron/luigi/actions/FilterAction.java
+++ b/java/src/main/java/org/pablotron/luigi/actions/FilterAction.java
@@ -1,6 +1,7 @@
 package org.pablotron.luigi.actions;
 
 import java.util.Map;
+
 import org.pablotron.luigi.actions.Action;
 import org.pablotron.luigi.FilterReference;
 import org.pablotron.luigi.Filter;
@@ -8,15 +9,41 @@ import org.pablotron.luigi.errors.LuigiError;
 import org.pablotron.luigi.errors.UnknownFilterError;
 import org.pablotron.luigi.errors.UnknownKeyError;
 
+/**
+ * Action that expands the given key and applies any specified filters.
+ */
 public final class FilterAction implements Action {
+  /**
+   * Value key.
+   */
   private final String key;
+
+  /**
+   * Array of filters to apply to value.
+   */
   private final FilterReference filters[];
 
+  /**
+   * Create a new FilterAction.
+   *
+   * @param key Template run argument key.
+   * @param filters Array of filter references.
+   */
   public FilterAction(final String key, final FilterReference filters[]) {
     this.key = key;
     this.filters = filters;
   }
 
+  /**
+   * Run this filter action and return the result as a string.
+   *
+   * @param filters Template filters.
+   * @param key Template run arguments.
+   *
+   * @return Action result.
+   *
+   * @throws LuigiError If an error occured while running this action.
+   */
   public String run(
     Map<String, Filter.Handler> filters,
     Map<String, String> args
@@ -33,7 +60,7 @@ public final class FilterAction implements Action {
       if (f == null)
         throw new UnknownFilterError(this.filters[i].name);
 
-      // run filter 
+      // run filter
       r = f.filter(r, this.filters[i].args, args);
     }
 
diff --git a/java/src/main/java/org/pablotron/luigi/actions/TextAction.java b/java/src/main/java/org/pablotron/luigi/actions/TextAction.java
index 32487be..4cd8aa0 100644
--- a/java/src/main/java/org/pablotron/luigi/actions/TextAction.java
+++ b/java/src/main/java/org/pablotron/luigi/actions/TextAction.java
@@ -1,17 +1,39 @@
 package org.pablotron.luigi.actions;
 
 import java.util.Map;
+
 import org.pablotron.luigi.actions.Action;
 import org.pablotron.luigi.Filter;
 import org.pablotron.luigi.errors.LuigiError;
 
+/**
+ * Action that returns a text literal.
+ */
 public final class TextAction implements Action {
+  /**
+   * Text literal.
+   */
   private final String text;
 
+  /**
+   * Create a new text action with the given text.
+   *
+   * @param text Text literal.
+   */
   public TextAction(final String text) {
     this.text = text;
   }
 
+  /**
+   * Run action and return text literal.
+   *
+   * @param filters Template filters (ignored).
+   * @param key Template run arguments (ignored).
+   *
+   * @return Text literal.
+   *
+   * @throws LuigiError If an error occured while running this action.
+   */
   public String run(
     final Map<String, Filter.Handler> filters,
     final Map<String, String> args
-- 
cgit v1.2.3