Switch from autodoc to doxygen for SDK C++ documentation.

* New build prerequisite doxygen (controllable via --with-doxygen).
* Adapted various headers to slightly different doxygen documentation
syntax, but much clean up still remains to be done (i.e., warnings
emitted by doxygen fixed).

6 files changed, 116 insertions, 274 deletions

diff --git a/odk/docs/cpp/ref/cpp.css b/odk/docs/cpp/ref/cpp.css
deleted file mode 100644
index 0d279b9bc9b5..000000000000
--- a/odk/docs/cpp/ref/cpp.css
+++ /dev/null
@@ -1,127 +0,0 @@
-/*      Autodoc css file for C++ documentation      */
-
-
-body   { background-color:#ffffff; }
-
-#adc-cppref a { color: #000000;	text-decoration: none; }
-#adc-cppref a:link { color: #18A303;	text-decoration: none; }
-#adc-cppref a:hover { text-decoration: underline; }
-#adc-cppref a:visited { color: #106802; }
-
-#adc-cppref h1     { font-size:20pt; margin-top:3pt; margin-bottom:7pt; }
-#adc-cppref h2     { font-family:Arial; font-size:16pt; margin-top:3pt; margin-bottom:5pt; }
-#adc-cppref h3     { font-size:13pt; margin-top:2pt; margin-bottom:3pt; }
-#adc-cppref h4     { font-size:10pt; font-weight:bold; margin-top:2pt; margin-bottom:1pt; }
-#adc-cppref dl     { margin-top:1pt; margin-bottom:1pt; }
-#adc-cppref dl.member  { margin-top:1pt; margin-bottom:1pt; 
-	     background-color:#c2f6ba; }
-#adc-cppref dt     { font-size:10pt; font-weight:bold; margin-top:2pt; margin-bottom:1pt; }
-#adc-cppref dt.member  { font-size:13pt; font-weight:bold; margin-top:2pt; margin-bottom:1pt; }
-#adc-cppref dt.simple  { font-size:10pt; font-weight:normal; margin-top:2pt; margin-bottom:1pt; }
-#adc-cppref dd     { font-size:10pt; margin-top:1pt; margin-bottom:1pt; }
-#adc-cppref dd.member  { font-size:10pt; margin-top:1pt; margin-bottom:1pt; background-color:#ffffff; }
-#adc-cppref p      { font-size:10pt; margin-top:3pt; margin-bottom:1pt; }
-#adc-cppref pre    { font-family:monospace; font-size:10pt; margin-top:1pt; margin-bottom:1pt; }
-#adc-cppref tr     { font-size:10pt; }
-#adc-cppref td     { font-size:10pt; }
-
-#adc-cppref dt.attention   { color:#ff0000; }
-
-#adc-cppref div.title      { text-align:center;  line-height:26pt; 
-		 background-color:#18a303; }
-#adc-cppref .subtitle      {background-color:#18a303; }
-
-#adc-cppref td.flagname    { background-color:#c2f6ba;
-	         font-family:Arial; font-size:8pt; font-weight:bold; }
-#adc-cppref td.flagyes     { font-family:Arial; font-size:8pt; font-weight:bold; }
-#adc-cppref td.flagno      { font-family:Arial; font-size:8pt; }
-#adc-cppref td.flagtext    { font-family:Arial; font-size:8pt; font-weight:bold; }
-
-#adc-cppref td.navimain
-               { background-color:#c2f6ba;
-                 font-family:Arial; font-size:12pt; font-weight:bold; }
-                 
-/* background-color:#eeeeff; color:#000000; */
-
-#adc-cppref td.navimainself
-               { background-color:#106802; color:#ffffff;
-                 font-family:Arial; font-size:12pt; font-weight:bold; }
-#adc-cppref td.navimainnone
-               {background-color:#c2f6ba; 
-                 font-family:Arial; font-size:12pt; }
-
-#adc-cppref div.define     { font-family:Arial; background-color:#c2f6ba; }
-
-#adc-cppref .nqclass       { color:#008800; }
-
-#adc-cppref h3.help        { background-color:#c2f6ba; margin-top:12pt; }
-
-#adc-cppref .btpubl        { color:#c2f6ba; }
-#adc-cppref .btprot        { color:#18a303; }
-#adc-cppref .btpriv        { color:#00ff00; }
-#adc-cppref .btvpubl       { color:#87c2e6; font-style:italic; }
-#adc-cppref .btvprot       { color:#18a303; font-style:italic; }
-#adc-cppref .btvpriv       { color:#00ff00; font-style:italic; }
-#adc-cppref .btself        { font-weight:bold; }
-
-#adc-cppref table { empty-cells:show; }
-
-#adc-cppref .childlist td, 
-#adc-cppref .commentedlinks td, 
-#adc-cppref .memberlist td, 
-#adc-cppref .title-table td, 
-#adc-cppref .subtitle td, 
-#adc-cppref .crosstitle td  { border: .1pt solid grey }
-
-#adc-cppref .flag-table td { border: .1pt solid #cccccc; } 
-
-#adc-cppref .table-in-method td, 
-#adc-cppref .table-in-data td, 
-#adc-cppref .navimain td, 
-#adc-cppref .navisub td, 
-#adc-cppref .expl-table td, 
-#adc-cppref .param-table td  { border: none; }
-
-
-/* Explanation of CSS classes:
-
-dl.member       provides coloured frame for function descriptions.
-dd.member       makes the content of this frame white
-
-dt.attention    special colour for @attention remarks
-
-div.title       HTML page headline
-.subtitle       headline of lists of members and similar
-
-                These are for the flagtables in classes:
-td.flagname     Flag name.
-td.flagyes      flag value "yes"
-td.flagno       flag value "no"
-td.flagtext     other flag value
-
-
-                These are for the main navigationbar:
-td.navimain, td.navimain a
-                Links in navibar.
-td.navimainself Text in navibar which refers to current page.
-td.navimainnone Text which links to nothing.
-
-
-div.define      Subtitles on the #define/macro descriptions page
-
-.nqclass        special color for classes in the qualification
-                on top of type pages like in:
-                ::nsp1::nsp2::_ClassXY_::
-
-h3.help         Subtitles on the help page
-
-                These are for the base class tree on class pages:
-.btpubl         public base class
-.btprot         protected
-.btpriv         private
-.btvpubl        virtual public
-.btvprot        virtual protected
-.btvpriv        virtual private
-.btself         placeholder for currently displayed class
-
-*/
diff --git a/odk/index.html b/odk/index.html
index f1baa8a40b83..de905cda3010 100644
--- a/odk/index.html
+++ b/odk/index.html
@@ -106,7 +106,7 @@
               </tr>
               <tr valign="top"> 
                 <td class="content4"><img src="docs/images/arrow-1.gif"></td>
-                <td colspan="2"><a href="docs/cpp/ref/names/index.html" title="link to the C++ API reference documentation">C++ Reference</a></td>
+                <td colspan="2"><a href="docs/cpp/ref/index.html" title="link to the C++ API reference documentation">C++ Reference</a></td>
                 <td class="content70">Reference documentation of the C++ UNO runtime and a 
 				set of C/C++ base and helper functions and classes to abstract from
 				the system layer.</td>
diff --git a/odk/pack/gendocu/Doxyfile b/odk/pack/gendocu/Doxyfile
new file mode 100644
index 000000000000..897462757723
--- /dev/null
+++ b/odk/pack/gendocu/Doxyfile
@@ -0,0 +1,51 @@
+##
+## Version: MPL 1.1 / GPLv3+ / LGPLv3+
+##
+## The contents of this file are subject to the Mozilla Public License Version
+## 1.1 (the "License"); you may not use this file except in compliance with
+## the License or as specified alternatively below. You may obtain a copy of
+## the License at http://www.mozilla.org/MPL/
+##
+## Software distributed under the License is distributed on an "AS IS" basis,
+## WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+## for the specific language governing rights and limitations under the
+## License.
+##
+## Major Contributor(s):
+## [ Copyright (C) 2012 Red Hat, Inc., Stephan Bergmann <sbergman@redhat.com>
+##   (initial developer) ]
+##
+## All Rights Reserved.
+##
+## For minor contributions see the git repository.
+##
+## Alternatively, the contents of this file may be used under the terms of
+## either the GNU General Public License Version 3 or later (the "GPLv3+"), or
+## the GNU Lesser General Public License Version 3 or later (the "LGPLv3+"),
+## in which case the provisions of the GPLv3+ or the LGPLv3+ are applicable
+## instead of those above.
+##
+
+PROJECT_BRIEF = %
+OUTPUT_DIRECTORY = %
+STRIP_FROM_PATH = %
+JAVADOC_AUTOBRIEF = YES
+
+EXTRACT_ALL = YES
+CASE_SENSE_NAMES = NO
+
+QUIET = %
+WARNINGS = YES
+WARN_IF_DOC_ERROR = YES
+WARN_FORMAT = "$file:$line: $text"
+
+INPUT = %
+RECURSIVE = YES
+
+HTML_OUTPUT = .
+
+GENERATE_LATEX = NO
+
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+PREDEFINED = __cplusplus SAL_CALL= "SAL_THROW(x)=throw x"
diff --git a/odk/pack/gendocu/main.dox b/odk/pack/gendocu/main.dox
new file mode 100644
index 000000000000..718f639f9d90
--- /dev/null
+++ b/odk/pack/gendocu/main.dox
@@ -0,0 +1,31 @@
+/*
+ * Version: MPL 1.1 / GPLv3+ / LGPLv3+
+ *
+ * The contents of this file are subject to the Mozilla Public License Version
+ * 1.1 (the "License"); you may not use this file except in compliance with
+ * the License or as specified alternatively below. You may obtain a copy of
+ * the License at http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+ * for the specific language governing rights and limitations under the
+ * License.
+ *
+ * Major Contributor(s):
+ * [ Copyright (C) 2012 Red Hat, Inc., Stephan Bergmann <sbergman@redhat.com>
+ *   (initial developer) ]
+ *
+ * All Rights Reserved.
+ *
+ * For minor contributions see the git repository.
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * either the GNU General Public License Version 3 or later (the "GPLv3+"), or
+ * the GNU Lesser General Public License Version 3 or later (the "LGPLv3+"),
+ * in which case the provisions of the GPLv3+ or the LGPLv3+ are applicable
+ * instead of those above.
+ */
+
+/// \mainpage
+///
+/// This is a reference documentation for the C++ source code.
diff --git a/odk/pack/gendocu/makefile.mk b/odk/pack/gendocu/makefile.mk
index fc9abf1881b8..93bd1aeb6509 100644
--- a/odk/pack/gendocu/makefile.mk
+++ b/odk/pack/gendocu/makefile.mk
@@ -68,38 +68,40 @@ JAVA_BEAN_SRC_FILES=\
         $(JAVA_SRC_DIR)$/com$/sun$/star$/beans$/OfficeConnection.java \
         $(JAVA_SRC_DIR)$/com$/sun$/star$/beans$/OfficeWindow.java
 
-AUTODOCPARAMS= -lg c++ \
-        -p sal $(INCOUT) -t sal -t osl -t rtl \
-        -p store $(INCOUT) -t store \
-        -p registry $(INCOUT) -t registry \
-        -p cppu $(INCOUT) -t cppu -t com -t typelib -t uno \
-        -p cppuhelper $(INCOUT) -t cppuhelper \
-        -p salhelper $(INCOUT) -t salhelper \
-        -p bridges $(INCOUT) -t bridges
-
 JAVADOCPARAMS= -use -splitindex -windowtitle "Java UNO Runtime Reference" -header $(JAVADOCREFNAME) -d $(DESTDIRGENJAVAREF) -sourcepath $(JAVA_SRC_DIR) -classpath $(SOLARBINDIR)$/ridl.jar -linkoffline ../../common/ref ./uno -linkoffline http://java.sun.com/j2se/1.4.1/docs/api ./java $(JAVA_PACKAGES)
 
 JAVADOCLOG = $(MISC)$/javadoc_log.txt
 
-.IF "$(SOLAR_JAVA)"!=""
-all: \
-    $(CPP_DOCU_INDEX_FILE) \
-    $(JAVA_DOCU_INDEX_FILE)
+all :
 
-.ELSE
-all: $(CPP_DOCU_INDEX_FILE)
-.ENDIF
+.IF "$(DOXYGEN)" != ""
+all : $(CPP_DOCU_INDEX_FILE)
+.END
 
+.IF "$(SOLAR_JAVA)" != ""
+all : $(JAVA_DOCU_INDEX_FILE)
+.END
 
-$(CPP_DOCU_CLEANUP_FLAG) : $(INCLUDELIST) $(PRJ)$/docs$/cpp$/ref$/cpp.css
+$(CPP_DOCU_CLEANUP_FLAG) : $(INCLUDELIST) Doxyfile main.dox
     @@-$(MY_DELETE_RECURSIVE) $(DESTDIRGENCPPREF)
     $(TOUCH) $@
 
-$(CPP_DOCU_INDEX_FILE) : $(CPP_DOCU_CLEANUP_FLAG)
-    -$(MKDIRHIER) $(@:d)        
-    $(MY_AUTODOC) -html $(DESTDIRGENCPPREF) -name $(CPPDOCREFNAME) $(AUTODOCPARAMS)
-    -rm $(@:d:d)$/cpp.css
-    $(MY_TEXTCOPY) $(MY_TEXTCOPY_SOURCEPRE) $(PRJ)$/docs$/cpp$/ref$/cpp.css $(MY_TEXTCOPY_TARGETPRE) $(@:d:d)$/cpp.css
+.IF "$(VERBOSE)" == "TRUE"
+MY_QUIET = NO
+.ELSE
+MY_QUIET = YES
+.END
+
+$(CPP_DOCU_INDEX_FILE) .ERRREMOVE : $(CPP_DOCU_CLEANUP_FLAG)
+    -$(MKDIRHIER) $(@:d)
+    $(SED) \
+        -e 's!^INPUT = %$$!INPUT = main.dox $(INCLUDETOPDIRLIST) $(INCLUDEFILELIST)!' \
+        -e 's!^OUTPUT_DIRECTORY = %$$!OUTPUT_DIRECTORY = $(DESTDIRGENCPPREF)!' \
+        -e 's!^PROJECT_BRIEF = %$$!PROJECT_BRIEF = $(CPPDOCREFNAME)!' \
+        -e 's!^QUIET = %$$!QUIET = $(MY_QUIET)!' \
+        -e 's!^STRIP_FROM_PATH = %$$!STRIP_FROM_PATH = $(SOLARINCDIR)!' \
+        Doxyfile > $(MISC)/Doxyfile
+    $(DOXYGEN) $(MISC)/Doxyfile
 
 $(JAVA_SRC_FILES) : $(SOLARCOMMONBINDIR)$/$$(@:f)
     -$(MKDIRHIER) $(@:d)        
diff --git a/odk/util/check.pl b/odk/util/check.pl
index 6598291754f3..7811635067e1 100644
--- a/odk/util/check.pl
+++ b/odk/util/check.pl
@@ -174,133 +174,18 @@ if (-d "$StartDir") {
 
     #check cpp docu, it is only a first and simple check
     # improvement required
-    print "check cpp docu: ";
-    if (-d "$StartDir/docs/cpp/ref") {
-    if (! -e "$StartDir/docs/cpp/ref/index.html") {
-        print "\nERROR: \"$StartDir/docs/cpp/ref/index.html\" is missing\n";
-        $return++;
-    }
-    if (! -d "$StartDir/docs/cpp/ref/index-files") {
-        print "\nERROR: \"$StartDir/docs/cpp/ref/index-files\" is missing\n";
-        $return++;
-    }
-    if (! -e "$StartDir/docs/cpp/ref/index-files/index-10.html") {
-        print "\nERROR: \"$StartDir/docs/cpp/ref/index-files/index-10.html\" is missing\n";
-        $return++;
-    }
-
-    # The commented out types from cppuhelper are missed by autodoc due to
-    # CPPUHELPER_DLLPUBLIC annotations:
-    my @dir_list = ( "com","com/sun","com/sun/star","com/sun/star/uno",
-             "com/sun/star/uno/Any","com/sun/star/uno/Type",
-             "com/sun/star/uno/Array",#"com/sun/star/uno/WeakReferenceHelper",
-             "com/sun/star/uno/Reference","com/sun/star/uno/WeakReference",
-             "com/sun/star/uno/Environment","com/sun/star/uno/Sequence",
-             "com/sun/star/uno/BaseReference","com/sun/star/uno/Mapping",
-             "com/sun/star/uno/ContextLayer","com/sun/star/uno/TypeDescription",
-             "osl","osl/File","osl/Pipe","osl/FileStatus","osl/FileBase",
-             "osl/Guard","osl/Mutex","osl/VolumeInfo","osl/GetGlobalMutex",
-             "osl/Security","osl/Profile","osl/DatagramSocket","osl/SocketAddr",
-             "osl/StreamPipe","osl/ResettableGuard","osl/AcceptorSocket",
-             "osl/ClearableGuard","osl/VolumeDevice","rtl","rtl/Uri","rtl/math",
-             "rtl/OUStringHash","rtl/MalformedUriException","rtl/OUStringBuffer",
-             "rtl/OUString","rtl/Reference","rtl/ByteSequence","rtl/OLocale",
-             "rtl/Logfile","rtl/OString","rtl/IReference","rtl/OStringBuffer",
-             "rtl/OStringHash","_typelib_CompoundTypeDescription","cppu",
-             "cppu/ContextEntry_Init","cppu/ImplInheritanceHelper10",
-             "cppu/ImplInheritanceHelper11","cppu/ImplInheritanceHelper12",
-             "cppu/WeakAggImplHelper1","cppu/WeakAggImplHelper2",
-             "cppu/WeakAggImplHelper3","cppu/WeakAggImplHelper4",
-             "cppu/WeakAggImplHelper5","cppu/WeakAggImplHelper6",
-             "cppu/WeakAggImplHelper7","cppu/WeakAggImplHelper8",
-             "cppu/WeakAggImplHelper9",
-             #"cppu/OMultiTypeInterfaceContainerHelperInt32","cppu/AccessControl",
-             #"cppu/OPropertyArrayHelper",
-             "cppu/ImplHelper1","cppu/ImplHelper2",
-             "cppu/ImplHelper3","cppu/ImplHelper4","cppu/ImplHelper5",
-             "cppu/ImplHelper6","cppu/ImplHelper7","cppu/ImplHelper8",
-             "cppu/ImplHelper9","cppu/WeakComponentImplHelper10",
-             "cppu/WeakComponentImplHelper11","cppu/WeakComponentImplHelper12",
-             #"cppu/UnoUrl",
-             "cppu/WeakComponentImplHelper1",
-             "cppu/WeakComponentImplHelper2","cppu/WeakComponentImplHelper3",
-             "cppu/WeakComponentImplHelper4","cppu/WeakComponentImplHelper5",
-             "cppu/WeakComponentImplHelper6","cppu/WeakComponentImplHelper7",
-             "cppu/WeakComponentImplHelper8","cppu/WeakComponentImplHelper9",
-             #"cppu/OInterfaceIteratorHelper",
-             #"cppu/OMultiTypeInterfaceContainerHelper","cppu/UnoUrlDescriptor",
-             #"cppu/IPropertyArrayHelper",
-             "cppu/OBroadcastHelperVar",
-             #"cppu/OComponentHelper","cppu/OWeakAggObject",
-             "cppu/ImplementationEntry","cppu/WeakImplHelper10",
-             "cppu/WeakImplHelper11","cppu/WeakImplHelper12",
-             #"cppu/OPropertySetHelper",
-             "cppu/ImplHelper10","cppu/ImplHelper11",
-             "cppu/ImplHelper12","cppu/WeakAggImplHelper10",
-             "cppu/WeakAggImplHelper11","cppu/WeakAggImplHelper12",
-             "cppu/ImplInheritanceHelper1","cppu/ImplInheritanceHelper2",
-             "cppu/ImplInheritanceHelper3","cppu/ImplInheritanceHelper4",
-             "cppu/ImplInheritanceHelper5","cppu/ImplInheritanceHelper6",
-             "cppu/ImplInheritanceHelper7","cppu/ImplInheritanceHelper8",
-             "cppu/ImplInheritanceHelper9",#"cppu/OTypeCollection",
-             "cppu/WeakAggComponentImplHelper10",
-             "cppu/WeakAggComponentImplHelper11",
-             "cppu/WeakAggComponentImplHelper12",
-             "cppu/WeakAggComponentImplHelper1",
-             "cppu/WeakAggComponentImplHelper2",
-             "cppu/WeakAggComponentImplHelper3",
-             "cppu/WeakAggComponentImplHelper4",
-             "cppu/WeakAggComponentImplHelper5",
-             "cppu/WeakAggComponentImplHelper6",
-             "cppu/WeakAggComponentImplHelper7",
-             "cppu/WeakAggComponentImplHelper8",
-             "cppu/WeakAggComponentImplHelper9",
-             "cppu/OMultiTypeInterfaceContainerHelperVar",
-             #"cppu/OInterfaceContainerHelper","cppu/OImplementationId",
-             "cppu/AggImplInheritanceHelper1","cppu/AggImplInheritanceHelper2",
-             "cppu/AggImplInheritanceHelper3","cppu/AggImplInheritanceHelper4",
-             "cppu/AggImplInheritanceHelper5","cppu/AggImplInheritanceHelper6",
-             "cppu/AggImplInheritanceHelper7","cppu/AggImplInheritanceHelper8",
-             "cppu/AggImplInheritanceHelper9","cppu/AggImplInheritanceHelper10",
-             "cppu/AggImplInheritanceHelper11","cppu/AggImplInheritanceHelper12",
-             "cppu/WeakImplHelper1","cppu/WeakImplHelper2","cppu/WeakImplHelper3",
-             "cppu/WeakImplHelper4","cppu/WeakImplHelper5","cppu/WeakImplHelper6",
-             "cppu/WeakImplHelper7","cppu/WeakImplHelper8","cppu/WeakImplHelper9",
-             #"cppu/OWeakObject",
-             "__store_FindData","_rtl_StandardModuleCount",
-             "RTUik","RTConstValue","_typelib_TypeDescriptionReference",
-             "_typelib_InterfaceMethodTypeDescription","store","RegistryKey",
-             "_typelib_Union_Init","_sal_Sequence","_typelib_Parameter_Init",
-             "_typelib_TypeDescription","_uno_Environment",
-             "_typelib_InterfaceAttributeTypeDescription",
-             "_rtl_ModuleCount","_uno_ExtEnvironment",
-             "_typelib_IndirectTypeDescription",
-             "Registry_Api","_oslFileStatus",
-             "_typelib_InterfaceMemberTypeDescription","RegistryValueList",
-             "RegistryTypeWriter_Api","_rtl_TextEncodingInfo",
-             "namespace_anonymous_1",
-             "_oslVolumeInfo","_uno_Interface",
-             "_typelib_InterfaceTypeDescription","_uno_Mapping","Registry",
-             "RegistryTypeReader_Api","_typelib_Uik",
-             "_typelib_ArrayTypeDescription",
-             "RegistryKeyArray","RegistryTypeReader","RegistryKeyNames",
-             "RTConstValueUnion","_typelib_UnionTypeDescription","_uno_Any",
-             "RegistryTypeWriter","_rtl_Locale","_typelib_CompoundMember_Init",
-             "_typelib_EnumTypeDescription","_typelib_MethodParameter");
-
-    foreach $i (@dir_list)
-    {
-        if (! -d "$StartDir/docs/cpp/ref/names/$i") {
-        $return++;
-        print "\nERROR: \"$StartDir/docs/cpp/ref/names/$i\" is missing\n";
+    if ($ENV{'DOXYGEN'} ne '') {
+        print "check cpp docu: ";
+        if (-d "$StartDir/docs/cpp/ref") {
+            if (! -e "$StartDir/docs/cpp/ref/index.html") {
+                print "\nERROR: \"$StartDir/docs/cpp/ref/index.html\" is missing\n";
+                $return++;
+            }
         } else {
-        print "+";
+            $return++;
         }
+        print "\n";
     }
-    } else {
-    $return++;
-    }
-    print "\n";
 
     #check java docu, it is only a first and simple check
     # improvement required