From fbd72a420b01af4c2bf7f5335c84b7bcc4d66fb9 Mon Sep 17 00:00:00 2001
From: Alena Laskavaia
Date: Tue, 1 Jun 2010 02:24:14 +0000
Subject: Javadoc
---
.../cdt/codan/core/model/cfg/IBasicBlock.java | 2 +-
.../cdt/codan/core/model/cfg/IBranchNode.java | 12 +++++
.../eclipse/cdt/codan/core/model/cfg/ICfgData.java | 8 +++
.../cdt/codan/core/model/cfg/IConnectorNode.java | 7 ++-
.../codan/core/model/cfg/IControlFlowGraph.java | 37 ++++++++++++-
.../cdt/codan/core/model/cfg/IExitNode.java | 3 ++
.../cdt/codan/core/model/cfg/IJumpNode.java | 10 +++-
.../cdt/codan/core/model/cfg/INodeFactory.java | 22 ++++++++
.../cdt/codan/core/model/cfg/ISingleIncoming.java | 6 +++
.../cdt/codan/core/model/cfg/ISingleOutgoing.java | 6 +++
.../param/IProblemPreferenceCompositeValue.java | 2 +-
.../core/param/IProblemPreferenceDescriptor.java | 45 +++++++++++++++-
.../codan/core/param/IProblemPreferenceValue.java | 6 +--
.../codan/core/param/ListProblemPreference.java | 40 +++++++++-----
.../cdt/codan/core/param/MapProblemPreference.java | 11 +++-
.../internal/core/cfg/AbstractBasicBlock.java | 61 +++++++---------------
.../core/cfg/AbstractSingleIncomingNode.java | 10 +++-
.../core/cfg/AbstractSingleOutgoingNode.java | 24 ++++-----
.../cdt/codan/internal/core/cfg/BranchNode.java | 9 ++--
.../codan/internal/core/cfg/ControlFlowGraph.java | 2 +-
20 files changed, 236 insertions(+), 87 deletions(-)
(limited to 'codan')
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBasicBlock.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBasicBlock.java
index ea3ed632c9a..fc261610ea0 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBasicBlock.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBasicBlock.java
@@ -1,7 +1,7 @@
package org.eclipse.cdt.codan.core.model.cfg;
/**
- * Control flow graph basic block node - super interface of all nodes.
+ * Control flow graph's basic block node - super interface of all nodes.
* It has set on incoming nodes and outgoing nodes.
*
*/
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBranchNode.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBranchNode.java
index 16cc25892bd..4d88c55376a 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBranchNode.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IBranchNode.java
@@ -15,9 +15,21 @@ package org.eclipse.cdt.codan.core.model.cfg;
*/
public interface IBranchNode extends IBasicBlock, ISingleIncoming,
ISingleOutgoing {
+ /**
+ * Then branch of "if" statement
+ */
public static String THEN = "then"; //$NON-NLS-1$
+ /**
+ * Else branch of "if" statement
+ */
public static String ELSE = "else"; //$NON-NLS-1$
+ /**
+ * Default branch of "switch" statement
+ */
public static String DEFAULT = "default"; //$NON-NLS-1$
+ /**
+ * @return label of a branch
+ */
String getLabel();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ICfgData.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ICfgData.java
index b8fab077aad..1e43450bd9e 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ICfgData.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ICfgData.java
@@ -18,7 +18,15 @@ package org.eclipse.cdt.codan.core.model.cfg;
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ICfgData {
+ /**
+ * @return data object
+ */
public abstract Object getData();
+ /**
+ * Sets data object for the node
+ *
+ * @param data
+ */
public abstract void setData(Object data);
}
\ No newline at end of file
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IConnectorNode.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IConnectorNode.java
index 60a5d404c59..16981c392df 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IConnectorNode.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IConnectorNode.java
@@ -1,9 +1,12 @@
package org.eclipse.cdt.codan.core.model.cfg;
/**
- * Connector node has multiple incoming branches and single outgoing
+ * Connector node has multiple incoming branches and single outgoing.
+ * Incoming nodes are usually instance of {@link IJumpNode}
*/
public interface IConnectorNode extends IBasicBlock, ISingleOutgoing {
- /** Backward connector has incoming node which comes from backward arcs */
+ /**
+ * @return true if one of the incoming arcs is backward arc
+ */
boolean hasBackwardIncoming();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IControlFlowGraph.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IControlFlowGraph.java
index 04d43591220..151bd3854fe 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IControlFlowGraph.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IControlFlowGraph.java
@@ -14,18 +14,53 @@ import java.util.Collection;
import java.util.Iterator;
/**
- * Represents control flow graph object
+ * Represents control flow graph (CFG) object.
+ * This is "normalized" control flow graph, with typed nodes:
+ *
+ * {@link IStartNode} - start node of the cfg (source)
+ * {@link IExitNode} - exit node of the cfg (sink)
+ * {@link IPlainNode} - has one incoming one outgoing
+ * {@link IDecisionNode} - has one incoming and the only node that can have
+ * multiple outcoming
+ * arcs
+ * {@link IConnectorNode} - the only node that can have multiple incoming
+ * arcs, and one outgoing
+ * {@link IJumpNode} - has one incoming and one outgoing but represent
+ * change of control direction
+ * {@link IBranchNode} - usually node where decision node connect to,
+ * labels represent a way where controls goes to
*/
public interface IControlFlowGraph {
+ /**
+ * @return start node of the graph. CFG only has one start node.
+ */
IStartNode getStartNode();
+ /**
+ * @return iterator over exit nodes of control flow graph. Exit nodes
+ * include return statement,
+ * and statements with throw and abort/exit functions.
+ */
Iterator getExitNodeIterator();
+ /**
+ * @return size of exit nodes list
+ */
int getExitNodeSize();
+ /**
+ * @return list of roots of dead code sections, they don't have incoming
+ * arcs
+ */
Iterator getUnconnectedNodeIterator();
+ /**
+ * @return size of unconnected nodes list
+ */
int getUnconnectedNodeSize();
+ /**
+ * @return collection of all nodes
+ */
Collection getNodes();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IExitNode.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IExitNode.java
index 1c626cc7f24..2ceeda9be0f 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IExitNode.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IExitNode.java
@@ -16,5 +16,8 @@ package org.eclipse.cdt.codan.core.model.cfg;
*
*/
public interface IExitNode extends IBasicBlock, ISingleIncoming {
+ /**
+ * @return reference to a start node a graph
+ */
IStartNode getStartNode();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IJumpNode.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IJumpNode.java
index e7b27063ab0..3511647022c 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IJumpNode.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/IJumpNode.java
@@ -2,13 +2,19 @@ package org.eclipse.cdt.codan.core.model.cfg;
/**
* Node that changes the control of the graph, i.e. passes control to non-next
- * statement. Can be used to implement gotos, break, continue, end of branches
+ * statement. Can be used to implement gotos, break, continue, end of branches.
+ * Outgoing node is always {@link IConnectorNode}
*/
public interface IJumpNode extends IBasicBlock, ISingleOutgoing {
/**
- * True of outgoing arc is backward one
+ * @return true of outgoing arc is backward one, see definition of backward
+ * arc in a "network" graph
*/
boolean isBackwardArc();
+ /**
+ * @return reference to a connector node to which this one "jumps" (same as
+ * outgoing node)
+ */
IConnectorNode getJumpNode();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/INodeFactory.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/INodeFactory.java
index dff1918b53c..643588df2c1 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/INodeFactory.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/INodeFactory.java
@@ -14,17 +14,39 @@ package org.eclipse.cdt.codan.core.model.cfg;
* Control Flow Graph Node factory
*/
public interface INodeFactory {
+ /**
+ * @return new plain node
+ */
IPlainNode createPlainNode();
+ /**
+ * @return new jump node
+ */
IJumpNode createJumpNode();
+ /**
+ * @return new decision node
+ */
IDecisionNode createDecisionNode();
+ /**
+ * @return new connector node
+ */
IConnectorNode createConnectorNode();
+ /**
+ * @param label
+ * @return new branch node
+ */
IBranchNode createBranchNode(String label);
+ /**
+ * @return new start node
+ */
IStartNode createStartNode();
+ /**
+ * @return new exit node
+ */
IExitNode createExitNode();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleIncoming.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleIncoming.java
index 2469ef09d96..9ac7f3000aa 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleIncoming.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleIncoming.java
@@ -1,5 +1,11 @@
package org.eclipse.cdt.codan.core.model.cfg;
+/**
+ * Node with one incoming arc
+ */
public interface ISingleIncoming {
+ /**
+ * @return single incoming node
+ */
IBasicBlock getIncoming();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleOutgoing.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleOutgoing.java
index 4a628482279..c95c2d29363 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleOutgoing.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/model/cfg/ISingleOutgoing.java
@@ -1,5 +1,11 @@
package org.eclipse.cdt.codan.core.model.cfg;
+/**
+ * Node with one outgoing arc
+ */
public interface ISingleOutgoing {
+ /**
+ * @return outgoing node
+ */
IBasicBlock getOutgoing();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceCompositeValue.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceCompositeValue.java
index f894c24846c..f44a6599b52 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceCompositeValue.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceCompositeValue.java
@@ -21,7 +21,7 @@ public interface IProblemPreferenceCompositeValue {
* Returns value of the child element of a given key
*
* @param key
- * @return
+ * @return value of the child preference
*/
Object getChildValue(String key);
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceDescriptor.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceDescriptor.java
index 3b2c8b7a190..0303020a5ef 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceDescriptor.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceDescriptor.java
@@ -30,13 +30,37 @@ import java.util.Map;
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IProblemPreferenceDescriptor extends Cloneable {
+ /**
+ * Type of the user preference
+ */
public enum PreferenceType {
+ /**
+ * String type, represented by string input field by default
+ */
TYPE_STRING("string"), //$NON-NLS-1$
+ /**
+ * Integer type, represented by integer input field by default
+ */
TYPE_INTEGER("integer"), //$NON-NLS-1$
+ /**
+ * Boolean type, represented by checkbox (boolean input field)
+ */
TYPE_BOOLEAN("boolean"), //$NON-NLS-1$
+ /**
+ * File type, represented by file picker input field
+ */
TYPE_FILE("file"), //$NON-NLS-1$
+ /**
+ * List type, represented by list (table) control
+ */
TYPE_LIST("list"), //$NON-NLS-1$
+ /**
+ * Map type, represented by composite of children fields
+ */
TYPE_MAP("map"), //$NON-NLS-1$
+ /**
+ * Custom type, represented by string input field by default
+ */
TYPE_CUSTOM("custom"); //$NON-NLS-1$
private String literal;
@@ -44,6 +68,11 @@ public interface IProblemPreferenceDescriptor extends Cloneable {
this.literal = literal;
}
+ /**
+ * @param name - name of the type literal (i.e. comes from name() or
+ * toString())
+ * @return type represented by this name
+ */
public static PreferenceType valueOfLiteral(String name) {
PreferenceType[] values = values();
for (int i = 0; i < values.length; i++) {
@@ -80,6 +109,12 @@ public interface IProblemPreferenceDescriptor extends Cloneable {
}
}
+ /**
+ * Key of the preference. Key must be java-like identified or number. Cannot
+ * contain dots. Cannot be null.
+ *
+ * @return key
+ */
String getKey();
/**
@@ -115,14 +150,22 @@ public interface IProblemPreferenceDescriptor extends Cloneable {
*/
String getToolTip();
+ /**
+ * default clone implementation
+ *
+ * @return clone of the object
+ */
Object clone();
+ /**
+ * @return parent preference
+ */
IProblemPreference getParent();
/**
* Combined key of values from parents plus itself separated by dot
*
- * @return
+ * @return qualified key
*/
String getQualifiedKey();
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceValue.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceValue.java
index 25033d75e03..cbe9f4f6dec 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceValue.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/IProblemPreferenceValue.java
@@ -39,7 +39,7 @@ public interface IProblemPreferenceValue extends Cloneable {
* Export value in string representation required for storing in eclipse
* preferences.
*
- * @return
+ * @return string representation of the value
*/
String exportValue();
@@ -47,8 +47,8 @@ public interface IProblemPreferenceValue extends Cloneable {
* Import value from string into internal object state.
*
* @param str
- * - string from preferences, previously exported by exportValue
- * method.
+ * - string from preferences, previously exported by exportValue
+ * method.
*/
void importValue(String str);
}
diff --git a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/ListProblemPreference.java b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/ListProblemPreference.java
index 4621ad9a810..333cb3132fc 100644
--- a/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/ListProblemPreference.java
+++ b/codan/org.eclipse.cdt.codan.core/src/org/eclipse/cdt/codan/core/param/ListProblemPreference.java
@@ -23,6 +23,10 @@ import java.util.Iterator;
*/
public class ListProblemPreference extends AbstractProblemPreference implements
IProblemPreferenceCompositeValue, IProblemPreferenceCompositeDescriptor {
+ /**
+ * Constant that represent a key for "shared" child preference (descriptor)
+ * of all elements
+ */
public static final String COMMON_DESCRIPTOR_KEY = "#"; //$NON-NLS-1$
protected ArrayList