From 4baa2f35d979b4e2336431460e313e055661327f Mon Sep 17 00:00:00 2001
From: Elliott Baron <ebaron@fedoraproject.org>
Date: Tue, 15 Dec 2009 00:04:03 -0500
Subject: Documented API classes/interfaces.

* org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/IPropertyFSM.java: Documented.
* org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/PropertyState.java: Likewise.
---
 .../eclipse/cdt/codan/extension/IPropertyFSM.java  | 14 +++++++++++++
 .../eclipse/cdt/codan/extension/PropertyState.java | 24 ++++++++++++++++++++--
 2 files changed, 36 insertions(+), 2 deletions(-)

(limited to 'org.eclipse.cdt.codan.extension/src/org/eclipse/cdt')

diff --git a/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/IPropertyFSM.java b/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/IPropertyFSM.java
index a8ace1e..872b6ae 100644
--- a/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/IPropertyFSM.java
+++ b/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/IPropertyFSM.java
@@ -12,12 +12,26 @@ package org.eclipse.cdt.codan.extension;
 
 import java.util.Set;
 
+/**
+ * A finite state machine that encodes a temporal state.
+ * It is a set of Property States with defined meanings and transitions.
+ */
 public interface IPropertyFSM {
 	
+	/**
+	 * Returns all Property States in this finite state machine.
+	 * @return a Set of all Property States
+	 */
 	public Set<PropertyState> getPropertyStates();
 	
+	/**
+	 * @return the initial state for this finite state machine
+	 */
 	public PropertyState getUninitState();
 	
+	/**
+	 * @return the error state indicating the temporal property was violated
+	 */
 	public PropertyState getErrorState();
 
 }
diff --git a/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/PropertyState.java b/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/PropertyState.java
index 95e334f..53462b6 100644
--- a/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/PropertyState.java
+++ b/org.eclipse.cdt.codan.extension/src/org/eclipse/cdt/codan/extension/PropertyState.java
@@ -12,18 +12,38 @@ package org.eclipse.cdt.codan.extension;
 
 import org.eclipse.cdt.core.dom.ast.IASTNode;
 
-public abstract class PropertyState {
-	
+/**
+ * A Property State represents the state of a temporal property.
+ * One or more Property States comprise an {@link IPropertyFSM}.
+ * Statements and expressions in the AST can cause a transition between
+ * states.
+ */
+public abstract class PropertyState {	
 	private String name;
 	
+	/**
+	 * Constructs an anonymous Property State.
+	 */
 	public PropertyState() {
 		this(null);
 	}
 	
+	/**
+	 * Constructs a Property State with an optional name used
+	 * to label it.
+	 * @param name - some meaningful name
+	 */
 	public PropertyState(String name) {
 		this.name = name;
 	}
 	
+	/**
+	 * Called while processing a control flow. Determine if node's
+	 * contents cause this state to transition to another state according
+	 * to the rules of your temporal property's finite state machine.
+	 * @param node - the IASTNode currently being processed
+	 * @return the PropertyState we transition to, or this if no transition
+	 */
 	public abstract PropertyState transition(IASTNode node);
 	
 	@Override
-- 
cgit