From 127ff8686b92bbd4a53d67c7ad091c20bb416eaa Mon Sep 17 00:00:00 2001
From: Daniel Bluhm <bluhmdj@ornl.gov>
Date: Thu, 28 May 2020 11:36:45 -0400
Subject: [PATCH] Add documentation to Fields

Signed-off-by: Daniel Bluhm <bluhmdj@ornl.gov>
---
 .../dev/annotations/processors/Fields.java    | 50 +++++++++++++++----
 1 file changed, 40 insertions(+), 10 deletions(-)

diff --git a/org.eclipse.ice.dev.annotations/src/main/java/org/eclipse/ice/dev/annotations/processors/Fields.java b/org.eclipse.ice.dev.annotations/src/main/java/org/eclipse/ice/dev/annotations/processors/Fields.java
index a82a52117..d1c72f496 100644
--- a/org.eclipse.ice.dev.annotations/src/main/java/org/eclipse/ice/dev/annotations/processors/Fields.java
+++ b/org.eclipse.ice.dev.annotations/src/main/java/org/eclipse/ice/dev/annotations/processors/Fields.java
@@ -4,7 +4,10 @@
 import java.util.List;
 
 /**
- * A simple container for fields discovered on a DataElement.
+ * A container for fields discovered on a DataElement.
+ *
+ * Fields can create and hold onto an instance of FieldBuilder to assist in
+ * constructing new Fields while visiting an AnnotationValue tree.
  */
 class Fields {
 	protected List<Field> fields;
@@ -15,10 +18,16 @@ public Fields() {
 		this.building = null;
 	}
 
+	/**
+	 * Begin construction of a new Field.
+	 */
 	public void begin() {
 		this.building = Field.builder();
 	}
 
+	/**
+	 * Finish the under construction Field and append to fields list.
+	 */
 	public void finish() {
 		this.fields.add(this.building.build());
 		this.building = null;
@@ -28,23 +37,41 @@ public List<Field> getFields() {
 		return fields;
 	}
 
+	/**
+	 * @return true if there is an instance of Field currently under construction.
+	 */
 	public boolean isBuilding() {
 		return this.building != null;
 	}
 
+	/**
+	 * @return true if the currently under construction Field is ready to be finished.
+	 */
 	public boolean isComplete() {
 		Field partial = this.building.build();
 		return (partial.getType() != null) && (partial.getName() != null);
 	}
 
+	/**
+	 * Shortcut to FieldBuilder.type().
+	 * @param type
+	 */
 	public void setType(final String type) {
 		this.building.type(Field.raw(type));
 	}
 
+	/**
+	 * Shortcut to FieldBuilder.name().
+	 * @param name
+	 */
 	public void setName(final String name) {
 		this.building.name(name);
 	}
 
+	/**
+	 * Shortcut to FieldBuilder.primitive().
+	 * @param primitive
+	 */
 	public void setPrimitive(boolean primitive) {
 		this.building.primitive(primitive);
 	}
@@ -54,24 +81,27 @@ public String toString() {
 		return fields.toString();
 	}
 
+	/**
+	 * Append field to fields list.
+	 * @param field
+	 */
 	public void add(Field field) {
 		this.fields.add(field);
 	}
 
+	/**
+	 * Extend fields with the contents of another Fields object.
+	 * @param fields
+	 */
 	public void addAll(Fields fields) {
 		this.fields.addAll(fields.getFields());
 	}
 
+	/**
+	 * Extend fields with a list of Field objects.
+	 * @param fields
+	 */
 	public void addAll(List<Field> fields) {
 		this.fields.addAll(fields);
 	}
-
-	public void addAll(Field[] fields) {
-		if (fields == null) {
-			return;
-		}
-		for (int i = 0; i < fields.length; i++) {
-			this.fields.add(fields[i]);
-		}
-	}
 }
\ No newline at end of file