Various minor documentation and formatting.

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

ccm-cms-types-agenda/src/com/arsdigita/cms/contenttypes/Agenda.java

@@ -54,10 +54,13 @@ import org.apache.log4j.Logger;
  **/
 public class Agenda extends GenericArticle {
 
-    /** Data object type for this domain object (for CMS compatibility) */
+    /** */
     private static final Logger s_log = Logger.getLogger(GenericArticle.class);
 
     //  PDL stuff  *************************************************************
+    /** Data object type for this domain object (for CMS compatibility) */
+    public static final String BASE_DATA_OBJECT_TYPE = 
+                               "com.arsdigita.cms.contenttypes.Agenda";
     /** PDL property name for summary */
     public static final String SUMMARY = "summary";
     /** PDL property name for agenda date */
@@ -72,9 +75,6 @@ public class Agenda extends GenericArticle {
     public static final String CONTACT_INFO = "contactInfo";
     /** PDL property name for creation date */
     public static final String CREATION_DATE = "creationDate";
-    /** Data object type for this domain object */
-    public static final String BASE_DATA_OBJECT_TYPE = 
-                               "com.arsdigita.cms.contenttypes.Agenda";
 
     /**
      * Default constructor. This creates a new (empty) Agenda.

ccm-cms/src/com/arsdigita/cms/ContentItem.java

@@ -480,11 +480,12 @@ public class ContentItem extends VersionedACSObject implements CustomCopy {
     }
 
     /**
-     * Fetch the display name of the content item. The display name for a {@link com.arsdigita.cms.ContentItem}
+     * Fetch the display name of the content item. The display name for a 
-     * is the name property.
+     * {@link com.arsdigita.cms.ContentItem} is the name property.
      *
      * @return The name of the content item
      */
+    @Override
     public String getDisplayName() {
         return getName();
     }

ccm-cms/src/com/arsdigita/cms/contentsection/ContentSectionConfig.java

@@ -261,9 +261,11 @@ public final class ContentSectionConfig extends AbstractConfig {
         Parameter.REQUIRED, false);
 
     /**
-     * XML file containing the category tree to load for this content section. Usually not loaded {
+     * XML file containing the category tree to load for this content section. 
+     * Usually not loaded {
      *
-     * @see m_useSectionCategories). The files listed as default values are demo material and must
+     * @see m_useSectionCategories). The files listed as default values are 
+     * demo material and must
      * be replaced in a production environment.
      */
     private final Parameter m_categoryFileList = new StringArrayParameter(

ccm-cms/src/com/arsdigita/cms/ui/item/Summary.java

@@ -99,27 +99,34 @@ public class Summary extends CMSContainer {
      * @pre ( state != null )
      * @pre ( parent != null )
      */
+    @Override
     public void generateXML(PageState state, Element parent) {
         if ( isVisible(state) ) {
 
+            // Determine the item's environment
             ContentItem item = getContentItem(state);
             ContentSection section = getContentSection(state);
             User user = Web.getWebContext().getUser();
 
+            // Setup xml element for item's properties
+            Element itemElement = new Element("cms:itemSummary",CMS.CMS_XML_NS);
+
+            // Determine item's name / url stub
+            itemElement.addAttribute("name",item.getName());
+
+            // obviously  getName() here gets the 'semantically meaningful name' 
+            // from database using class DataType. It is not localizable! And 
+            // it is not really 'semantically meaningful'
+            String objectType = item.getObjectType().getName();
+
+            // Quasimodo: ObjectType for summary
+            itemElement.addAttribute("objectType", objectType);
+
             // NOT USED - CUSTOMIZED SUMMARY
             // Take advantage of caching in the CMS Dispatcher.
             // XMLGenerator xmlGenerator = section.getXMLGenerator();
             // xmlGenerator.generateXML(state, parent, SUMMARY);
 
-            // ITEM
-            Element itemElement = new Element("cms:itemSummary",CMS.CMS_XML_NS);
-            itemElement.addAttribute("name",item.getName());
-
-            String objectType = item.getObjectType().getName();
-
-            // Quasimodo: ObjectType for summary
-            itemElement.addAttribute("objectType", objectType);
-
             String descriptionAttribute = "";
             if ( objectType.equals("NewsItem") || objectType.equals("Article") ) {
                 descriptionAttribute = "lead";

ccm-cms/src/com/arsdigita/cms/ui/type/ContentTypeAdminPane.java

@@ -65,14 +65,25 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
     private final ACSObjectSelectionModel m_model;
     private final ContentTypeRequestLocal m_type;
 
+    /**
+     * Constructs an admin pane. It is containing 
+     * (a)
+     * a list of available content types in a 
+     * given content section and adds a link to make additional content types
+     * available (out of a list of installed, but available in a given content
+     * section).
+     */
     public ContentTypeAdminPane() {
+        
+        // 
         super(new Label(gz("cms.ui.types")),
-                new ContentTypeListModelBuilder());
+              new ContentTypeListModelBuilder() );  //list with all Types avail.
 
         m_model = new ACSObjectSelectionModel(getSelectionModel());
         m_type = new SelectionRequestLocal();
 
         ActionLink addTypeLink = new ActionLink(new Label(gz("cms.ui.type.add")));
+
         AddTypeContainer addTypeContainer = new AddTypeContainer();
         getBody().add(addTypeContainer);
         getBody().connect(addTypeLink, addTypeContainer);
@@ -93,17 +104,25 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
         addAction(new TypeSecurityContainer(addTypeLink), ActionGroup.ADD);
     }
 
+    @Override
     public void register(Page p) {
         super.register(p);
 
         p.addActionListener(new ActionListener() {
 
+            /**
+             * 
+             * @param e 
+             */
+            @Override
             public void actionPerformed(ActionEvent e) {
                 final PageState state = e.getPageState();
                 ContentType contentType = (ContentType) m_model.getSelectedObject(state);
                 ContentSection section = CMS.getContext().getContentSection();
                 if (contentType == null) {
-                    final String template = state.getRequest().getParameter(ContentSectionPage.SET_TEMPLATE);
+                    final String template = state.getRequest()
+                                            .getParameter(ContentSectionPage
+                                                          .SET_TEMPLATE);
                     if (template != null) {
                         DataCollection da = SessionManager.getSession().retrieve(SectionTemplateMapping.BASE_DATA_OBJECT_TYPE);
                         DomainCollection c = new DomainCollection(da);
@@ -141,13 +160,20 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
         });
     }
 
-    private class AddTypeContainer extends GridPanel implements ActionListener, FormProcessListener {
+    /**
+     * 
+     */
+    private class AddTypeContainer extends GridPanel implements ActionListener, 
+                                                                FormProcessListener {
 
         private Label m_noTypesAvailable =
                 new Label(gz("cms.ui.type.select.none"));
         private SelectType m_selectType;
         private CreateType m_createType;
 
+        /**
+         * 
+         */
         AddTypeContainer() {
             super(1);
             Section selectSection = new Section();
@@ -164,6 +190,7 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
 
             Section addSection = new Section() {
 
+                @Override
                 public final boolean isVisible(final PageState state) {
                     return super.isVisible(state)
                             && !ContentSection.getConfig().getHideUDCTUI();
@@ -177,6 +204,11 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
             add(addSection);
         }
 
+        /**
+         * 
+         * @param e 
+         */
+        @Override
         public void actionPerformed(ActionEvent e) {
             PageState s = e.getPageState();
             ContentSection section = CMS.getContext().getContentSection();
@@ -195,9 +227,9 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
     }
 
     /**
-     *  This class is essentially a copy of the CancelListener
+     *  This class is essentially a copy of the CancelListener inside of
-     *  inside of ModalPanel.  We could not use the one in ModalPanel
+     *  ModalPanel.  We could not use the one in ModalPanel because it was
-     *  becaue it was protected
+     *  protected
      */
     private final class CancelListener implements FormSubmissionListener {
 
@@ -207,6 +239,7 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
             m_form = form;
         }
 
+        @Override
         public void submitted(FormSectionEvent event)
                 throws FormProcessException {
             PageState state = event.getPageState();
@@ -215,7 +248,7 @@ public final class ContentTypeAdminPane extends BaseAdminPane {
                 throw new FormProcessException("cancelled");
             }
         }
-    }
+    }  // end private class 
 
     private void resetPane(PageState state) {
         getBody().reset(state);

ccm-cms/src/com/arsdigita/cms/ui/type/ContentTypeListModelBuilder.java

@@ -34,17 +34,27 @@ import java.util.NoSuchElementException;
  * Builds a dynamic list of content types for a content section.
  */
 class ContentTypeListModelBuilder extends LockableImpl
-        implements ListModelBuilder {
+                                  implements ListModelBuilder {
+
+    /**
+     * 
+     * @param l
+     * @param state
+     * @return 
+     */
     public ListModel makeModel(List l, final PageState state) {
         return new Model();
     }
 
+    /**
+     * 
+     */
     private class Model implements ListModel {
+
         private ContentTypeCollection m_types;
 
         Model() {
-            final ContentSection section =
+            final ContentSection section = CMS.getContext().getContentSection();
-                CMS.getContext().getContentSection();
 
             m_types = section.getContentTypes(true);
             m_types.addOrder(ContentType.LABEL);

ccm-core/src/com/arsdigita/domain/DomainObject.java

@@ -330,6 +330,8 @@ public abstract class DomainObject {
      * This should only be used inside of a setXXX
      * method.
      *
+     * @param attr
+     * @param value
      * @see com.arsdigita.persistence.DataObject#set(String, Object)
      **/
     protected void set(String attr, Object value) {
@@ -349,6 +351,8 @@ public abstract class DomainObject {
      * If the upper bound of the multiplicity is greater than 1 then the
      * {@link #add(String, DataObject)} method should be used.
      *
+     * @param attr
+     * @param dobj
      * @see com.arsdigita.persistence.DataObject#set(String, Object)
      */
     protected void setAssociation(String attr, DomainObject dobj) {
@@ -363,6 +367,7 @@ public abstract class DomainObject {
     /**
      * Remove the DomainObject from a DataAssociation
      *
+     * @param da
      * @see com.arsdigita.persistence.DataAssociation#remove(DataObject)
      **/
     public void removeFromAssociation(DataAssociation da) {
@@ -372,6 +377,8 @@ public abstract class DomainObject {
     /**
      * Add the DomainObject to a DataAssociation
      *
+     * @param da
+     * @return 
      * @see com.arsdigita.persistence.DataAssociation#add(DataObject)
      **/
     public DataObject addToAssociation(DataAssociation da) {

ccm-core/src/com/arsdigita/persistence/metadata/DataType.java

@@ -32,33 +32,36 @@ package com.arsdigita.persistence.metadata;
  * @author <a href="mailto:rhs@mit.edu">rhs@mit.edu</a>
  * @version $Revision: #10 $ $Date: 2004/08/16 $
  */
-
 abstract public class DataType extends ModelElement {
 
     
 
-    private com.redhat.persistence.metadata.ObjectType m_type;
+    private final com.redhat.persistence.metadata.ObjectType m_type;
 
     /**
      * Constructs a new DataType with the given name.
      *
-     * @param name The semantically meaningful name of the datatype.
+     * @param obj
-     **/
+     */
-
+    protected DataType(com.redhat.persistence.metadata.ObjectType obj) {
-    protected DataType
-	(com.redhat.persistence.metadata.ObjectType obj) {
         super(obj.getRoot(), obj.getModel(), obj);
 	m_type = obj;
     }
 
     /**
      * Returns the semantically meaningful name of this datatype.
-     *
+     * 
+     * pb(2014-08-05): Kind of outdated because it just retrieves the name
+     * from database which is not globalized and not globalizable given the 
+     * current code. And it is not really 'semantically meaningful'. It's more
+     * to retrieve an abbreviation or an id.
+     * 
      * @return the semantically meaningful name of this datatype.
-     **/
+     * @deprecated without direct replacement. Avoid this method for user 
-
+     *             interface!
+     */
     public String getName() {
-	return m_type.getName();
+        return m_type.getName();
     }
 
 
@@ -68,10 +71,9 @@ abstract public class DataType extends ModelElement {
      * of this DataType.
      *
      * @return The fully qualified name of this DataType.
-     **/
+     */
-
     public String getQualifiedName() {
-	return m_type.getQualifiedName();
+        return m_type.getQualifiedName();
     }
 
 
@@ -81,10 +83,9 @@ abstract public class DataType extends ModelElement {
      * compound.
      *
      * @return True if this DataType is a compound type. False otherwise.
-     **/
+     */
-
     public boolean isCompound() {
-	return m_type.isCompound();
+        return m_type.isCompound();
     }
 
     /**
@@ -93,8 +94,7 @@ abstract public class DataType extends ModelElement {
      * from which compound types can be created.
      *
      * @return True if this DataType is a simple type. False otherwise.
-     **/
+     */
-
     public boolean isSimple() {
         return !isCompound();
     }

ccm-core/src/com/redhat/persistence/metadata/Model.java

@@ -21,19 +21,31 @@ package com.redhat.persistence.metadata;
 import java.util.HashMap;
 
 /**
- * Model
+ * Model.
+ * 
+ * A dot-separated String of names.
+ * The part after the last dot is the 'name' of the model.
+ * The part before the last dot is the 'parent', or the path to the name.
+ * 
+ * usually a package name.
+ * , used to connect a class to pdl (Data Object
+ * Type, usually BASE_DATA_OBJECT_TYPE)
  *
  * @author Rafael H. Schloming <rhs@mit.edu>
  * @version $Revision: #8 $ $Date: 2004/08/16 $
- **/
+ */
-
 public class Model {
 
-    
+    /** Map containing the model dot separated parts. The key contains each 
-
+     *  part of the dot-separated string, the value part the
+     *  (still dot-separated)path to that key (it's parent).                 */
     private static final HashMap MODELS = new HashMap();
 
+    /** 
+     * Get a Modal instance. Singelton pattern!
+     */
     public static final Model getInstance(String model) {
+
         if (model == null) {
             return null;
         }
@@ -48,12 +60,15 @@ public class Model {
                     result = (Model) MODELS.get(model);
                 } else {
                     int dot = model.lastIndexOf('.');
-                    Model parent;
+                    Model parent;  
                     String name;
                     if (dot > -1) {
+                        //recursively deconstructs the model string to it's parts.
                         parent = getInstance(model.substring(0, dot));
                         name = model.substring(dot + 1);
                     } else {
+                        // finally deconstructed, name is now the (originally)
+                        // first part of the model without a parent.
                         parent = null;
                         name = model;
                     }
@@ -67,10 +82,18 @@ public class Model {
         return result;
     }
 
+    /** The parent model of the injected model (reconstructed doku)           */
     private final Model m_parent;
+    /** The name (last part) of the injected model (reconstructed doku)       */
     private final String m_name;
+    /** The ????  of the injected model (reconstructed doku)           */
     private final String m_qualifiedName;
 
+    /**
+     * Private Constructor to instantiate a Model. 
+     * @param parent
+     * @param name 
+     */
     private Model(Model parent, String name) {
         m_parent = parent;
         m_name = name;
@@ -82,14 +105,26 @@ public class Model {
 
     }
 
+    /**
+     * Getter ...
+     * @return 
+     */
     public Model getParent() {
         return m_parent;
     }
 
+    /**
+     * Getter ..
+     * @return 
+     */
     public String getName() {
         return m_name;
     }
 
+    /**
+     * Getter... 
+     * @return 
+     */
     public String getQualifiedName() {
         return  m_qualifiedName;
     }

ccm-core/src/com/redhat/persistence/metadata/ObjectType.java

@@ -281,10 +281,12 @@ public class ObjectType extends Element {
         }
     }
 
+    @Override
     Object getElementKey() {
         return getQualifiedName();
     }
 
+    @Override
     public String toString() {
         return getQualifiedName();
     }