Added some more documentation

layout/base/public/nsIFrameReflow.h

@@ -67,6 +67,7 @@ struct nsReflowMetrics {
 
 /**
  * The reason the frame is being reflowed.
+ *
  * XXX Should probably be a #define so it can be extended for specialized
  * reflow interfaces...
  *
@@ -149,7 +150,6 @@ struct nsReflowState {
  * extension bits).
  *
  * @see #Reflow()
- * @see #CreateContinuingFrame()
  */
 typedef PRUint32 nsReflowStatus;
 

layout/base/public/nsIReflowCommand.h

@@ -41,19 +41,71 @@ struct nsSize;
  * target frame (the frame for which the reflow command is destined). Reflow
  * commands are processed by invoking the frame's Reflow() member function.
  *
- * @see nsIFrame#ContentChanged()
- * @see nsIFrame#ContentReplaced()
+ * The typical flow of control for a given reflow command starts with a content
+ * change notification. The content notifications are sent to document observers.
+ * The presentation shell forwards the notifications to the style set. The style
+ * system responds to the notifications by creating new frame (or destroying
+ * existing frames) as appropriate, and then generating a reflow command.
+ *
+ * @see nsIDocumentObserver
+ * @see nsIStyleSet
+ * @see nsIFrameReflow#Reflow()
  * @see nsIPresShell#AppendReflowCommand()
  * @see nsIPresShell#ProcessReflowCommands()
  */
 class nsIReflowCommand : public nsISupports {
 public:
   enum ReflowType {
-    // Reflow commands generated in response to a content append,
-    // insert, and remove notification. The target of the reflow
-    // command is the container frame itself.
+    /**
+     * Reflow command generated by the style system in response to a
+     * ContentAppended content notification. The target frame of the reflow
+     * command is the container frame itself. The "child frame" is a linked
+     * list of newly created child frames.
+     *
+     * The target frame should insert the new frames into its child list, and
+     * then reflow the child frames using an eReflowReason_Initial reflow reason.
+     *
+     * ContentInserted content notifications also generate a FrameAppended reflow
+     * command if the container frame has no existing child frames.
+     *
+     * @see #GetTarget()
+     * @see #GetChildFrame()
+     */
     FrameAppended,
+
+    /**
+     * Reflow command generated by the style system in response to a
+     * ContentInserted content notification. The target frame of the reflow
+     * command is the container frame itself. The "child frame" is the newly
+     * created child frame. The "previous sibling" frame is the existing frame
+     * immediately preceding where the newly created frame should be inserted.
+     * If the newly created frame should be the target frame's first child frame
+     * then "previous sibling" will be nsnull.
+     *
+     * The target frame should insert the new frame immediately after the previous
+     * frame, and then reflow the new frame using an eReflowReason_Initial reflow
+     * reason.
+     *
+     * The target frame is determined as follows:
+     *   - find the previous existing frame and use its content parent
+     *   - if there is no previous frame then find the frame that follows and use
+     *     its content parent
+     *
+     * @see #GetTarget()
+     * @see #GetChildFrame()
+     * @see #GetPrevSiblingFrame()
+     */
     FrameInserted,
+
+    /**
+     * Reflow command generated by the style system in response to a
+     * ContentRemoved content notification. The "child frame" is the frame
+     * associated with the content that has been removed. The target frame
+     * is the content parent of the "child frame".
+     *
+     * @see #GetTarget()
+     * @see #GetChildFrame()
+     */
     FrameRemoved,
 
     // This reflow command is used when a leaf node's content changes
@@ -69,6 +121,8 @@ public:
     // reflow command is the frame that changed style.
     StyleChanged,
 
+    // XXX Everything below is speculative...
+
     // When an incremental reflow operation affects a next-in-flow,
     // these commands are used to get the next-in-flow to update
     // itself.