Some code and documentation cleanup.

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353584 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/poi/hpsf/DocumentSummaryInformation.java

@@ -255,11 +255,7 @@ public class DocumentSummaryInformation extends SpecialPropertySet
 
 
     /**
-     * <p>Returns <code>true</code> if the custom links are hampered
+     * <p>Returns <code>true</code> if the custom links are dirty.</p> <p>
-     * by excessive noise, for all applications.</p> <p>
-     *
-     * <strong>FIXME (3):</strong> Explain this some more! I (Rainer)
-     * don't understand it.</p>
      *
      * @return The linksDirty value
      */

src/java/org/apache/poi/hpsf/MutableSection.java

@@ -506,7 +506,7 @@ public class MutableSection extends Section
 
 
     /**
-     * <p>Returns this section's properties.</p>
+     * <p>Gets this section's properties.</p>
      * 
      * @return this section's properties.
      */
@@ -521,14 +521,13 @@ public class MutableSection extends Section
     /**
      * <p>Gets a property.</p>
      * 
-     * <p><strong>FIXME (2):</strong> This method ensures that properties and
-     * preprops are in sync. Cleanup this awful stuff!</p>
-     * 
      * @param id The ID of the property to get
      * @return The property or <code>null</code> if there is no such property
      */
     public Object getProperty(final long id)
     {
+        /* Calling getProperties() ensures that properties and preprops are in
+         * sync.</p> */
         getProperties();
         return super.getProperty(id);
     }

src/java/org/apache/poi/hpsf/SummaryInformation.java

@@ -264,10 +264,9 @@ public class SummaryInformation extends SpecialPropertySet
      * <strong>when this method is implemented. Please note that the
      * return type is likely to change!</strong></p>
      *
-     * <p><strong>FIXME (3) / Hint to developers:</strong> Drew Varner
+     * <p><strong>Hint to developers:</strong> Drew Varner &lt;Drew.Varner -at-
-     * &lt;Drew.Varner -at- sc.edu&gt; said that this is an image in
+     * sc.edu&gt; said that this is an image in WMF or Clipboard (BMP?) format.
-     * WMF or Clipboard (BMP?) format. He also provided two links that
+     * He also provided two links that might be helpful: <a
-     * might be helpful: <a
      * href="http://www.csn.ul.ie/~caolan/publink/file/OLE2SummaryAgainst_file-3.27.patch"
      * target="_blank">http://www.csn.ul.ie/~caolan/publink/file/OLE2SummaryAgainst_file-3.27.patch</a>
      * and <a

src/java/org/apache/poi/hpsf/wellknown/PropertyIDMap.java

@@ -17,7 +17,9 @@
         
 package org.apache.poi.hpsf.wellknown;
 
+import java.util.Collections;
 import java.util.HashMap;
+import java.util.Map;
 
 /**
  * <p>This is a dictionary which maps property ID values to property
@@ -29,12 +31,8 @@ import java.util.HashMap;
  * should treat them as unmodifiable, copy them and modifiy the
  * copies.</p>
  *
- * <p><strong>FIXME (3):</strong> Make the singletons unmodifiable. However, 
+ * @author Rainer Klute <a
- * since this requires to use a {@link HashMap} delegate instead of
+ * href="mailto:klute@rainer-klute.de">&lt;klute@rainer-klute.de&gt;</a>
- * extending {@link HashMap} and thus requires a lot of stupid typing, I won't
- * do that for the time being.</p>
- *
- * @author Rainer Klute (klute@rainer-klute.de)
  * @version $Id$
  * @since 2002-02-09
  */
@@ -104,7 +102,31 @@ public class PropertyIDMap extends HashMap
      * document</p> */
     public static final int PID_APPNAME = 18;
 
-    /** <p>FIXME (2): ID of the property that denotes...</p> */
+    /** <p>ID of the property that denotes whether read/write access to the
+     * document is allowed or whether is should be opened as read-only. It can
+     * have the following values:</p>
+     * 
+     * <table>
+     *  <tbody>
+     *   <tr>
+     *    <th><p>Value</p></th>
+     *    <th><p>Description</p></th>
+     *   </tr>
+     *   <tr>
+     *    <th><p>0</p></th>
+     *    <th><p>No restriction</p></th>
+     *   </tr>
+     *   <tr>
+     *    <th><p>2</p></th>
+     *    <th><p>Read-only recommended</p></th>
+     *   </tr>
+     *   <tr>
+     *    <th><p>4</p></th>
+     *    <th><p>Read-only enforced</p></th>
+     *   </tr>
+     *  </tbody>
+     * </table>
+     */
     public static final int PID_SECURITY = 19;
 
 
@@ -242,6 +264,18 @@ public class PropertyIDMap extends HashMap
 
 
 
+    /**
+     * <p>Creates a {@link PropertyIDMap} backed by another map.</p>
+     * 
+     * @param map The instance to be created is backed by this map.
+     */
+    public PropertyIDMap(final Map map)
+    {
+        super(map);
+    }
+
+
+
     /**
      * <p>Puts a ID string for an ID into the {@link
      * PropertyIDMap}.</p>
@@ -300,7 +334,8 @@ public class PropertyIDMap extends HashMap
             m.put(PID_THUMBNAIL, "PID_THUMBNAIL");
             m.put(PID_APPNAME, "PID_APPNAME");
             m.put(PID_SECURITY, "PID_SECURITY");
-            summaryInformationProperties = m;
+            summaryInformationProperties =
+                new PropertyIDMap(Collections.unmodifiableMap(m));
         }
         return summaryInformationProperties;
     }
@@ -335,7 +370,8 @@ public class PropertyIDMap extends HashMap
             m.put(PID_MANAGER, "PID_MANAGER");
             m.put(PID_COMPANY, "PID_COMPANY");
             m.put(PID_LINKSDIRTY, "PID_LINKSDIRTY");
-            documentSummaryInformationProperties = m;
+            documentSummaryInformationProperties =
+                new PropertyIDMap(Collections.unmodifiableMap(m));
         }
         return documentSummaryInformationProperties;
     }

src/testcases/org/apache/poi/hpsf/basic/TestWrite.java

@@ -29,7 +29,6 @@ import java.io.OutputStream;
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.io.UnsupportedEncodingException;
-import java.util.Arrays;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;