documentation

2 files changed, 100 insertions, 4 deletions

diff --git a/writerfilter/documentation/doxygen/images/ooxmlimportchain.png b/writerfilter/documentation/doxygen/images/ooxmlimportchain.png
new file mode 100644
index 000000000000..509f1cab5b90
--- /dev/null
+++ b/writerfilter/documentation/doxygen/images/ooxmlimportchain.png
diff --git a/writerfilter/inc/ooxml/OOXMLDocument.hxx b/writerfilter/inc/ooxml/OOXMLDocument.hxx
index 233774acb80f..3797988b69ca 100644
--- a/writerfilter/inc/ooxml/OOXMLDocument.hxx
+++ b/writerfilter/inc/ooxml/OOXMLDocument.hxx
@@ -4,9 +4,9 @@
  *
  *  $RCSfile: OOXMLDocument.hxx,v $
  *
- *  $Revision: 1.9 $
+ *  $Revision: 1.10 $
  *
- *  last change: $Author: hbrinkm $ $Date: 2007-06-04 08:15:11 $
+ *  last change: $Author: hbrinkm $ $Date: 2007-06-29 15:38:16 $
  *
  *  The Contents of this file are made available subject to
  *  the terms of GNU Lesser General Public License Version 2.1.
@@ -54,6 +54,37 @@
 #include <com/sun/star/xml/sax/XParser.hpp>
 #endif
 
+/**
+   <h1>Import of OOXML WordprocessingML Documents</h1>
+
+   The following picture shows the classes involved in importing OOXML
+   WordprocessingML documents.
+
+   @image html ooxmlimportchain.png
+
+   The DOCX consists of parts. Each part is an XML document.  The
+   OOXMLDocument opens the DOCX and creates a SAX parser for the part
+   containing the main document content. The OOXMLDocument creates a
+   SAX handler, too. This handler is set as the handler for the events
+   created by the parser. Finally the OOXMLDocument initiates the
+   parsing process.
+
+   The SAX handler hosts a stack of contexts. Each context is an
+   instance of a class derived from OOXMLContext. There is a context
+   class for each <define> in the model.xml.
+
+   For a detailed information about how the contexts are handled see
+   the documentation for OOXMLContext.
+
+   The contexts know how to convert an element in OOXML to the
+   intermediate format that the domain mapper understands. They
+   enumerate the according entity in OOXML by sending the according
+   events to the domain mapper.
+
+   The domain mapper knows how to convert the intermediate format to
+   API calls. It takes the events sent by the contexts and uses the
+   core API to insert the according elements to the core.
+ */
 
 namespace ooxml
 {
@@ -69,8 +100,19 @@ public:
 
     virtual ~OOXMLStream() {}
 
+    /**
+       Returns parser for this stream.
+     */
     virtual uno::Reference<xml::sax::XParser> getParser() = 0;
+
+    /**
+       Returns input stream for this stream.
+     */
     virtual uno::Reference<io::XInputStream> getInputStream() = 0;
+
+    /**
+       Returns component context for this stream.
+     */
     virtual uno::Reference<uno::XComponentContext> getContext() = 0;
 };
 
@@ -84,19 +126,73 @@ public:
 
     virtual ~OOXMLDocument() {}
 
-    virtual void resolve(Stream &) = 0;
+    /**
+       Resolves this document to a stream handler.
+
+       @param rStream     stream handler to resolve this document to
+     */
+    virtual void resolve(Stream & rStream) = 0;
+
+    /**
+       Returns string representation of the type of this reference.
 
+       DEBUGGING PURPOSE ONLY.
+     */
     virtual string getType() const = 0;
 
+    /**
+       Resolves a footnote to a stream handler.
+
+       @param rStream       stream handler to resolve to
+       @param rNoteId       id of the footnote to resolve
+     */
     virtual void resolveFootnote(Stream & rStream,
                                  const rtl::OUString & rNoteId) = 0;
+
+    /**
+       Resolves an endnote to a stream handler.
+
+       @param rStream       stream handler to resolve to
+       @param rNoteId       id of the endnote to resolve
+     */
     virtual void resolveEndnote(Stream & rStream,
                                 const rtl::OUString & rNoteId) = 0;
+
+    /**
+       Resolves a comment to a stream handler.
+
+       @param rStream       stream handler to resolve to
+       @param rComment      id of the comment to resolve
+     */
     virtual void resolveComment(Stream & rStream,
-                                const rtl::OUString & rNoteId) = 0;
+                                const rtl::OUString & rCommentId) = 0;
+
+    /**
+       Resolves a header to a stream handler.
+
+       @param rStream       stream handler to resolve to
+       @param type          type of header to resolve:
+                            NS_ooxml::LN_Value_ST_HrdFtr_even     header on even page
+                            NS_ooxml::LN_Value_ST_HrdFtr_default  header on right page
+                            NS_ooxml::LN_Value_ST_HrdFtr_first    header on first page
+
+       @param rId           id of the header
+     */
     virtual void resolveHeader(Stream & rStream,
                                const sal_Int32 type,
                                const rtl::OUString & rId) = 0;
+
+    /**
+       Resolves a footer to a stream handler.
+
+       @param rStream       stream handler to resolve to
+       @param type          type of footer to resolve:
+                            NS_ooxml::LN_Value_ST_HrdFtr_even     header on even page
+                            NS_ooxml::LN_Value_ST_HrdFtr_default  header on right page
+                            NS_ooxml::LN_Value_ST_HrdFtr_first    header on first page
+
+       @param rId           id of the header
+    */
     virtual void resolveFooter(Stream & rStream,
                                const sal_Int32 type,
                                const rtl::OUString & rId) = 0;