Document what's in the type of the map entry.

And organize xmltypes.hxx a bit to make it easier to follow.  Also
rename MID_FLAG_PROPERTY_MAY_EXCEPT to MID_FLAG_PROPERTY_MAY_THROW.

Change-Id: If18f07159a613555cf031bea5e07c04c7c45abec

2 files changed, 110 insertions, 64 deletions

diff --git a/include/xmloff/maptype.hxx b/include/xmloff/maptype.hxx
index 8bff58daec76..7b263fba0f2b 100644
--- a/include/xmloff/maptype.hxx
+++ b/include/xmloff/maptype.hxx
@@ -36,10 +36,56 @@ struct XMLPropertyMapEntry
     sal_uInt16      mnNameSpace;    /** declares the Namespace in which this
                                         property exists */
     enum ::xmloff::token::XMLTokenEnum meXMLName;       /// XML-Name
-    sal_uInt32      mnType;         /** Bit 0..23 : XML-Type of its value
-                                        Bit 24..31: The flags specifies
-                                                    additional rules how
-                                                    to im/export the porperty */
+
+    /**
+     * The lowest 14 bits specify the basic XML type of the property value, of
+     * which the 11th bit specifies the application type.  The basic type has
+     * the 11th bit off and the 14th bit on.  For the most part, the lower 14
+     * bits are used as a single value.
+     *
+     * <p>The next 4 bits specify the family type of the property value. This
+     * can be one of the following:</p>
+     *
+     * <ul>
+     *     <li>XML_TYPE_PROP_GRAPHIC</li>
+     *     <li>XML_TYPE_PROP_DRAWING_PAGE</li>
+     *     <li>XML_TYPE_PROP_PAGE_LAYOUT</li>
+     *     <li>XML_TYPE_PROP_HEADER_FOOTER</li>
+     *     <li>XML_TYPE_PROP_TEXT</li>
+     *     <li>XML_TYPE_PROP_PARAGRAPH</li>
+     *     <li>XML_TYPE_PROP_RUBY</li>
+     *     <li>XML_TYPE_PROP_SECTION</li>
+     *     <li>XML_TYPE_PROP_TABLE</li>
+     *     <li>XML_TYPE_PROP_TABLE_COLUMN</li>
+     *     <li>XML_TYPE_PROP_TABLE_ROW</li>
+     *     <li>XML_TYPE_PROP_TABLE_CELL</li>
+     *     <li>XML_TYPE_PROP_LIST_LEVEL</li>
+     *     <li>XML_TYPE_PROP_CHART</li>
+     * </ul>
+     *
+     * <p>The next 6 bits are not used.</p>
+     *
+     * <p>The last 12 bits specify additional rules on how to special-case the
+     * value during import and export.  This value may be a combination of the
+     * following flags:</p>
+     *
+     * <ul>
+     *     <li>MID_FLAG_PROPERTY_MAY_THROW</li>
+     *     <li>MID_FLAG_DEFAULT_ITEM_EXPORT</li>
+     *     <li>MID_FLAG_MUST_EXIST</li>
+     *     <li>MID_FLAG_MERGE_ATTRIBUTE</li>
+     *     <li>MID_FLAG_MERGE_PROPERTY</li>
+     *     <li>MID_FLAG_MULTI_PROPERTY</li>
+     *     <li>MID_FLAG_ELEMENT_ITEM_IMPORT</li>
+     *     <li>MID_FLAG_ELEMENT_ITEM_EXPORT</li>
+     *     <li>MID_FLAG_SPECIAL_ITEM_IMPORT</li>
+     *     <li>MID_FLAG_SPECIAL_ITEM_EXPORT</li>
+     *     <li>MID_FLAG_NO_PROPERTY_IMPORT</li>
+     *     <li>MID_FLAG_NO_PROPERTY_EXPORT</li>
+     * </ul>
+     */
+    sal_uInt32 mnType;
+
     sal_Int16       mnContextId;    /// User defined id for context filtering
     SvtSaveOptions::ODFDefaultVersion   mnEarliestODFVersionForExport;// no export when the used ODF version is lower than this
 
diff --git a/include/xmloff/xmltypes.hxx b/include/xmloff/xmltypes.hxx
index 4226166993b7..2d22d208f89d 100644
--- a/include/xmloff/xmltypes.hxx
+++ b/include/xmloff/xmltypes.hxx
@@ -35,80 +35,89 @@
 
 #define MID_FLAG_MASK                   0x00003fff
 
-// Import only: the xml attribute's value is evaluated by a call to
-// handleSpecialItem instead of calling the property handler's importXML method
-#define MID_FLAG_SPECIAL_ITEM_IMPORT    0x80000000
+// Import only: In general, properties may not throw exception, but
+// this one may. If it throws an IllegalArgumentException, it will be
+// silently ignored. This should be used for properties whose values
+// cannot be checked. (E.g., the printer paper tray: The tray names
+// are different for all printers, and we don't know ahead whether a
+// printer supports the trays in the current document.)
+#define MID_FLAG_PROPERTY_MAY_THROW     0x00100000
 
-// Export only: the property's value is exported by a call to handleSpecialItem
-// instead of calling the property handler's exportXML method
-#define MID_FLAG_SPECIAL_ITEM_EXPORT    0x20000000
-#define MID_FLAG_SPECIAL_ITEM           0xa0000000  // both import and export
+// Export only: When exporting defaults, export this property even if it is
+// not set
+#define MID_FLAG_DEFAULT_ITEM_EXPORT    0x00200000
+
+// Import and Export: The property in question must exist. No call to
+// hasPropertyByName is required.
+#define MID_FLAG_MUST_EXIST             0x00400000
+
+// Export only: If an xml attribute with the same name has been exported
+// already, supply its value to the exportXML call and delete the existing
+// attribute afterwards.
+#define MID_FLAG_MERGE_ATTRIBUTE        0x00800000
+
+// Import only: If a property with the same name has been set already, supply
+// the current value to the importXML call.
+#define MID_FLAG_MERGE_PROPERTY         0x01000000
+
+// Import only: there are more entries for the same xml attribute existing
+#define MID_FLAG_MULTI_PROPERTY         0x02000000
 
 // the map entry denotes the name of an element item
-#define MID_FLAG_ELEMENT_ITEM_IMPORT    0x08000000
 #define MID_FLAG_ELEMENT_ITEM_EXPORT    0x04000000
-#define MID_FLAG_ELEMENT_ITEM           0x0c000000  // both import and export
+#define MID_FLAG_ELEMENT_ITEM_IMPORT    0x08000000
 
-// the attribute is ignored (not yet implemented)
-#define MID_FLAG_NO_PROPERTY_IMPORT     0x40000000
+#define MID_FLAG_ELEMENT_ITEM           0x0c000000  // both import and export
 
 // the property is ignored
 #define MID_FLAG_NO_PROPERTY_EXPORT     0x10000000
-#define MID_FLAG_NO_PROPERTY            0x50000000  // both import and export
 
-// Import only: there are more entries for the same xml attribute existing
-#define MID_FLAG_MULTI_PROPERTY         0x02000000
-
-// Import only: If a property with the same name has been set already, supply
-// the current value to the importXML call.
-#define MID_FLAG_MERGE_PROPERTY         0x01000000
+// the attribute is ignored (not yet implemented)
+#define MID_FLAG_NO_PROPERTY_IMPORT     0x40000000
 
-// Export only: If an xml attribute with the same name has been exported
-// already, supply its value to the exportXML call and delete the existing
-// attribute afterwards.
-#define MID_FLAG_MERGE_ATTRIBUTE        0x00800000
+#define MID_FLAG_NO_PROPERTY            0x50000000  // both import and export
 
-// Import and Export: The property in question must exist. No call to
-// hasPropertyByName is required.
-#define MID_FLAG_MUST_EXIST             0x00400000
+// Import only: the xml attribute's value is evaluated by a call to
+// handleSpecialItem instead of calling the property handler's importXML method
+#define MID_FLAG_SPECIAL_ITEM_IMPORT    0x80000000
 
-// Export only: When exporting defaults, export this property even if it is
-// not set
-#define MID_FLAG_DEFAULT_ITEM_EXPORT    0x00200000
+// Export only: the property's value is exported by a call to handleSpecialItem
+// instead of calling the property handler's exportXML method
+#define MID_FLAG_SPECIAL_ITEM_EXPORT    0x20000000
+#define MID_FLAG_SPECIAL_ITEM           0xa0000000  // both import and export
 
-// Import only: In general, properties may not throw exception, but
-// this one may. If it throws an IllegalArgumentException, it will be
-// silently ignored. This should be used for properties whose values
-// cannot be checked. (E.g., the printer paper tray: The tray names
-// are different for all printers, and we don't know ahead whether a
-// printer supports the trays in the current document.)
-#define MID_FLAG_PROPERTY_MAY_EXCEPT    0x00100000
 
 #define XML_TYPE_PROP_SHIFT 14
 #define XML_TYPE_PROP_MASK (0xf << XML_TYPE_PROP_SHIFT)
 
-#define XML_TYPE_PROP_START (0x1 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_GRAPHIC (0x1 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_DRAWING_PAGE (0x2 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_PAGE_LAYOUT (0x3 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_START         (0x1 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_GRAPHIC       (0x1 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_DRAWING_PAGE  (0x2 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_PAGE_LAYOUT   (0x3 << XML_TYPE_PROP_SHIFT)
 #define XML_TYPE_PROP_HEADER_FOOTER (0x4 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_TEXT (0x5 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_PARAGRAPH (0x6 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_RUBY (0x7 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_SECTION (0x8 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_TABLE (0x9 << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_TABLE_COLUMN (0xa << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_TABLE_ROW (0xb << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_TABLE_CELL (0xc << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_LIST_LEVEL (0xd << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_CHART (0xe << XML_TYPE_PROP_SHIFT)
-#define XML_TYPE_PROP_END (0xf << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_TEXT          (0x5 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_PARAGRAPH     (0x6 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_RUBY          (0x7 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_SECTION       (0x8 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_TABLE         (0x9 << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_TABLE_COLUMN  (0xa << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_TABLE_ROW     (0xb << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_TABLE_CELL    (0xc << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_LIST_LEVEL    (0xd << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_CHART         (0xe << XML_TYPE_PROP_SHIFT)
+#define XML_TYPE_PROP_END           (0xf << XML_TYPE_PROP_SHIFT)
 
+#define XML_TYPE_APP_SHIFT 10
 
+#define XML_SC_TYPES_START   (0x1 << XML_TYPE_APP_SHIFT)
+#define XML_SD_TYPES_START   (0x2 << XML_TYPE_APP_SHIFT)
+#define XML_TEXT_TYPES_START (0x3 << XML_TYPE_APP_SHIFT)
+#define XML_SCH_TYPES_START  (0x4 << XML_TYPE_APP_SHIFT)
+#define XML_PM_TYPES_START   (0x5 << XML_TYPE_APP_SHIFT) // page master
+#define XML_DB_TYPES_START   (0x6 << XML_TYPE_APP_SHIFT)
 
 // XML-data-type-ID's
 
-
 // simple types, no special compare necessary
 #define XML_TYPE_BUILDIN_CMP 0x00002000
 
@@ -151,11 +160,6 @@
 #define XML_TYPE_RECTANGLE_WIDTH    0x00000102          // the Width member of a awt::Rectangle as a measure
 #define XML_TYPE_RECTANGLE_HEIGHT   0x00000103          // the Height member of a awt::Rectangle as a measure
 
-#define XML_TYPE_APP_SHIFT 10
-#define XML_SC_TYPES_START  (0x1 << XML_TYPE_APP_SHIFT)
-#define XML_SD_TYPES_START  (0x2 << XML_TYPE_APP_SHIFT)
-
-#define XML_TEXT_TYPES_START (0x3 << XML_TYPE_APP_SHIFT)
 #define XML_TYPE_TEXT_CROSSEDOUT_STYLE  (XML_TEXT_TYPES_START +   0)
 #define XML_TYPE_TEXT_CASEMAP       (XML_TEXT_TYPES_START +   1)
 #define XML_TYPE_TEXT_FONTFAMILYNAME (XML_TEXT_TYPES_START +   2)
@@ -286,10 +290,6 @@
 #define XML_SW_TYPE_BITMAPREPOFFSETX    (XML_TEXT_TYPES_START + 124)
 #define XML_SW_TYPE_BITMAPREPOFFSETY    (XML_TEXT_TYPES_START + 125)
 
-#define XML_SCH_TYPES_START (0x4 << XML_TYPE_APP_SHIFT)
-#define XML_PM_TYPES_START  (0x5 << XML_TYPE_APP_SHIFT) // page master
-#define XML_DB_TYPES_START  (0x6 << XML_TYPE_APP_SHIFT)
-
 #endif // INCLUDED_XMLOFF_XMLTYPES_HXX
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */