Added documentation

git-svn-id: https://svn.libreccm.org/ccm/trunk@2404 8810af33-2d31-482b-a856-94f89814c4df

ccm-core/src/com/arsdigita/bebop/Component.java

@@ -249,7 +249,8 @@ public interface Component extends Lockable {
      * malfunction and produce errors like "Widget ... isn't
      * associated with any Form"
      *
-     * @pre p != null */
+     * @pre p != null 
+     */
     void register(Page p);
 
     /**
@@ -260,7 +261,8 @@ public interface Component extends Lockable {
      * components can implement it as a no-op.
      *
      * @pre f != null
-     * @pre m != null */
+     * @pre m != null 
+     */
     void register(Form f, FormModel m);
 
     /* Properties that will get copied straight to the output,

ccm-core/src/com/arsdigita/bebop/ModalContainer.java

@@ -26,7 +26,7 @@ import java.util.Iterator;
 import org.apache.log4j.Logger;
 
 /**
- * A modal container is a container that manages visibility for a set of
+ * ModalContainer is a container that manages visibility for a set of
  * components. It allows only one of its children to be visible. One of its
  * children can be selected as the default visible component. If none is
  * selected the child with index equal to zero is used. The modal container
@@ -53,6 +53,19 @@ public class ModalContainer extends SimpleContainer implements Resettable {
         super(tagName, xmlns);
     }
 
+    /**
+     * Registers state parameters for the page with its model.
+     *
+     * Used here to set the visibility of the component.
+     *
+     * The super class' method is empty, so the rule "Always call 
+     * <code>super.register</code> when you override <code>register</code> 
+     * doessn't apply here.
+     *
+     * @pre p != null 
+     * @param p 
+     */
+    @Override
     public void register(Page p) {
         Assert.isUnlocked(this);
 

ccm-core/src/com/arsdigita/bebop/SimpleComponent.java

@@ -68,10 +68,50 @@ public class SimpleComponent extends Completable
         return result;
     }
 
+    /**
+     * Registers state parameters for the page with its model. Documentation
+     * from Interface Componment:
+     *
+     * A simple component with a state parameter <code>param</code> would do
+     * the following in the body of this method:
+     * <pre>
+     *   p.addComponent(this);
+     *   p.addComponentStateParam(this, param);
+     * </pre>
+     *
+     * You should override this method to set the default visibility
+     * of your component:
+     *
+     * <pre>
+     * public void register(Page p) {
+     *     super.register(p);
+     *     p.setVisibleDefault(childNotInitiallyShown,false);
+     *     p.setVisibleDefault(anotherChild, false);
+     * }
+     * </pre>
+     *
+     * Always call <code>super.register</code> when you override
+     * <code>register</code>.  Otherwise your component may
+     * malfunction and produce errors like "Widget ... isn't
+     * associated with any Form"
+     *
+     * @pre p != null 
+     * @param p 
+     */
     public void register(Page p) {
         return;
     }
 
+    /**
+     * Registers form parameters with the form model for this form.
+     * This method is only important for {@link FormSection form sections}
+     * and {@link com.arsdigita.bebop.form.Widget widgets} (components that
+     * have a connection to an HTML form). Other components can implement it
+     * as a no-op.
+     *
+     * @pre f != null
+     * @pre m != null 
+     */
     public void register(Form f, FormModel m) {
         return;
     }