Documentation enhancements

2 files changed, 82 insertions, 53 deletions

diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java
index f5c41273d5f..4eabc6cdb49 100644
--- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java
+++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java
@@ -259,6 +259,10 @@ public class DefaultVMModelProxyStrategy implements IVMModelProxy {
 	 * determine how elements of those types may be (or are) affected by
 	 * [event], the answer being a collection of IModelDelta flags.
 	 * 
+	 * A response of IModeDelta.CONTENT has a special meaning. If we return that
+	 * flag for an IVMNode, it means the <i>collection</i> of elements of that
+	 * type are affected. It is not a statement on the elements themselves.
+	 * 
 	 * Optimization 1: If the first-level child node does not have
 	 * <code>IModelDelta.CONTENT</code> but one of its descendants does, then
 	 * for optimization reasons we return <code>IModelDelta.STATE</code>
@@ -621,25 +625,30 @@ public class DefaultVMModelProxyStrategy implements IVMModelProxy {
         }
     }
 
-    /**
-     * Calls the specified child nodes to build the delta for the given event.
-     * @param childNodes Map of nodes to be invoked, and the corresponding delta 
-     * flags that they will generate.  This map is generated with a call to 
-     * {@link #getChildNodesWithDeltaFlags(Object)}.  
-     * @param delta The delta object to build on.  This delta should have been 
-     * generated by this node, unless the full delta path is not being calculated
-     * due to an optimization.
-     * @param event The event object that the delta is being built for.
-     * @param rm The result token to invoke when the delta is completed.
-     */
+	/**
+	 * Calls the specified child nodes (of [node]) to build the delta for the
+	 * given event.
+	 * 
+	 * @param childNodes
+	 *            Map of nodes to be invoked, and the corresponding delta flags
+	 *            that they may (or will) generate. This map is generated with a
+	 *            call to {@link #getChildNodesWithDeltaFlags(Object)}.
+	 * @param delta
+	 *            The delta object to build on. This delta should have been
+	 *            generated by this node, unless the full delta path is not
+	 *            being calculated due to an optimization.
+	 * @param event
+	 *            The event object that the delta is being built for.
+	 * @param rm
+	 *            The result monitor to invoke when the delta is completed.
+	 */
     protected void callChildNodesToBuildDelta(final IVMNode node, final Map<IVMNode,Integer> childNodes, final VMDelta delta, 
         final Object event, final RequestMonitor rm) 
     {
         assert childNodes.size() != 0;
 
-        // Check if any of the child nodes are will generate IModelDelta.SELECT  or 
-        // IModelDelta.EXPAND flags.  If so, we must calculate the index for this 
-        // VMC.
+		// Check if any of the child nodes might generate a delta that requires
+		// us to calculate the index for this VMC.
         boolean calculateOffsets = false;
         for (int childDelta : childNodes.values()) {
             if ( (childDelta & (IModelDelta.SELECT | IModelDelta.EXPAND | IModelDelta.INSERTED | IModelDelta.REMOVED)) != 0 ) {
@@ -752,7 +761,8 @@ public class DefaultVMModelProxyStrategy implements IVMModelProxy {
 
 	/**
 	 * Convenience method that returns what each of the child nodes returns from
-	 * {@link #getDeltaFlags(IVMNode, ModelDelta, Object)}.
+	 * {@link #getDeltaFlags(IVMNode, ModelDelta, Object)}. Children that return
+	 * IModelDelta.NO_CHANGE are omitted.
 	 */
     protected Map<IVMNode, Integer> getChildNodesWithDeltaFlags(IVMNode node, ModelDelta parentDelta, Object e) {
         Map<IVMNode, Integer> nodes = new HashMap<IVMNode, Integer>(); 
diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java
index 09452c03bec..f380088ae6a 100644
--- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java
+++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java
@@ -52,45 +52,64 @@ public interface IVMNode extends IElementContentProvider
      * Retrieves the view model provider that this node is configured with.
      */
     public IVMProvider getVMProvider();
-    
-    /**
-     * Returns the potential delta flags that would be generated by this node 
-     * for the given event.  
-     * @param event Event to process.
-     * @return IModelDelta flags
-     * @see #buildDelta(Object, VMDelta, int, RequestMonitor)
-     * @see IModelDelta
-     */
+
+	/**
+	 * Returns a set of IModelDelta delta flags that indicate how elements of
+	 * this node (type) may be, or are, affected by the given event. If the
+	 * implementation cannot make a definitive assessment synchronously, then it
+	 * should provide the "worst case scenario" (all ways in which the elements
+	 * <i>may</i> be affected). If a delta flag is not returned, it means for
+	 * certain that elements of this node will not be affected in that way. That
+	 * information allows us to optimize the delta creation.
+	 * 
+	 * <p>
+	 * A response of IModeDelta.CONTENT has a special meaning. If we return that
+	 * flag, it means the <i>collection</i> of elements of our type are
+	 * affected. It is not a statement on the elements themselves.
+	 * 
+	 * @param event
+	 *            the event the caller is processing
+	 * @return IModelDelta flags
+	 * @see #buildDelta(Object, VMDelta, int, RequestMonitor)
+	 * @see IModelDelta
+	 */
     public int getDeltaFlags(Object event);
-    
-    /**
-     * Builds model delta information based on the given event.  
-     * <p>
-     * Model deltas, which are used to control the state of elements in the viewer, are 
-     * generated by the layout nodes by recursively calling this method on all the nodes 
-     * in the layout tree.  Each node implements two methods: {@link #getDeltaFlags(Object)}, 
-     * and <code>buildDelta()</code>.  A parent node which is processing a 
-     * <code>buildDelta</code> operation needs to determine which of its elements are
-     * affected by a given event, set appropriate flags on these elements, and then 
-     * it needs to call its child nodes with those elements to give the child nodes a 
-     * chance to add onto the delta.  
-     * </p>
-     * <p>
-     * The <code>getDeltaFlags()</code> is a synchronous
-     * call which tells the parent node whether on not to call the child node's 
-     * <code>buildDelta</code> with the given event.  If a child node return 
-     * <code>true</code>, it only indicates that the node may add delta flags, but it
-     * does not require it to do so.
-     * </p>  
-     * 
-     * @param event Event to process.
-     * @param parent Parent model delta node that this object should add delta
-     * data to.
-     * @param nodeOffset The offset of the first element in this node.  This offset
-     * depends on the elements returned by the siblings of this layout node.
-     * @param requestMonitor Return token, which notifies the caller that the calculation is
-     * complete.
-     */
+
+	/**
+	 * Builds model delta information based on the given event.
+	 * <p>
+	 * Model deltas, which are used to control the state of elements in the
+	 * viewer, are generated by the layout nodes by recursively calling this
+	 * method on all the nodes in the layout tree. Each node implements two
+	 * methods: {@link #getDeltaFlags(Object)}, and <code>buildDelta()</code>. A
+	 * parent node which is processing a <code>buildDelta</code> operation needs
+	 * to determine which of its elements are affected by a given event, set
+	 * appropriate flags on these elements, and then it needs to call its child
+	 * nodes with those elements to give the child nodes a chance to add onto
+	 * the delta.
+	 * </p>
+	 * <p>
+	 * The <code>getDeltaFlags()</code> is a synchronous call which tells the
+	 * parent node whether on not it needs to call us for a given child node,
+	 * given the event it is processing. If a child node returns something other
+	 * than IModelDelta.NO_CHANGE, then it is providing the set of flags that we
+	 * <i>might</i> end up adding to the delta, but it doesn't mean we are
+	 * obligated to or will.
+	 * </p>
+	 * 
+	 * @param event
+	 *            Event to process.
+	 * @param parent
+	 *            Parent model delta node that this object should add delta data
+	 *            to.
+	 * @param nodeOffset
+	 *            The offset of the first element in this node. This offset
+	 *            depends on the elements returned by the siblings of this
+	 *            layout node.
+	 * @param requestMonitor
+	 *            Return token, which notifies the caller that the calculation
+	 *            is complete.
+	 */
     public void buildDelta(Object event, VMDelta parent, int nodeOffset, RequestMonitor requestMonitor);
 
     /**