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).

3 files changed, 106 insertions, 22 deletions

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)