cleaned up Doxygen documentation + included Funambol API

git-svn-id: https://zeitsenke.de/svn/SyncEvolution/trunk@693 15ad00c4-1369-45f4-8270-35d70d36bdcd

5 files changed, 65 insertions, 49 deletions

diff --git a/Doxyfile b/Doxyfile
index 842d73c9..e7bab4fd 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -25,7 +25,7 @@ DOXYFILE_ENCODING      = UTF-8
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = SyncEvolution
+PROJECT_NAME           = "SyncEvolution and Funambol"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 
@@ -113,7 +113,7 @@ FULL_PATH_NAMES        = YES
 # If left blank the directory from which doxygen is run is used as the 
 # path to strip.
 
-STRIP_FROM_PATH        = 
+STRIP_FROM_PATH        = $(STRIP_FROM_PATH)
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of 
 # the path mentioned in the documentation of a class, which tells 
@@ -383,7 +383,7 @@ GENERATE_DEPRECATEDLIST= YES
 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.
 
-ENABLED_SECTIONS       = 
+ENABLED_SECTIONS       = API
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines 
 # the initial value of a variable or define consists of for it to appear in 
@@ -477,7 +477,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = src test
+INPUT                  = src test $(CLIENT_LIBRARY)
 
 # This tag can be used to specify the character encoding of the source files that 
 # doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default 
@@ -519,7 +519,7 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories 
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = **/.svn */src/client-api/* */src/core/vocl */src/client-api.build/* */src/core/boost/*
+EXCLUDE_PATTERNS       = **/.svn */src/client-api/ */src/core/vocl */src/core/boost/* */e-cal-check-timezones.*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names 
 # (namespaces, classes, functions, etc.) that should be excluded from the output. 
@@ -590,7 +590,7 @@ FILTER_SOURCE_FILES    = NO
 # then you must also enable this option. If you don't then doxygen will produce 
 # a warning and turn it on anyway
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body 
 # of functions and classes directly in the documentation.
@@ -601,7 +601,7 @@ INLINE_SOURCES         = NO
 # doxygen to hide any special comment blocks from generated source code 
 # fragments. Normal C and C++ comments will always remain visible.
 
-STRIP_CODE_COMMENTS    = YES
+STRIP_CODE_COMMENTS    = NO
 
 # If the REFERENCED_BY_RELATION tag is set to YES (the default) 
 # then for each documented function all documented 
diff --git a/Makefile-gen.am b/Makefile-gen.am
index b657b2a0..e8bcc9fb 100644
--- a/Makefile-gen.am
+++ b/Makefile-gen.am
@@ -80,12 +80,17 @@ doc-pak : README NEWS COPYING
 description-pak : description
 	cp $< $@
 
+# Build "html" inside the build dir, using source files
+# from the SyncEvolution source directory and (if built)
+# the installed client-api.build directory.
 .PHONY: doc clean-html
 doc:
 	rm -rf html
-	export VERSION=$(VERSION); \
+	export VERSION="SyncEvolution $(VERSION)"; \
 	export OUTPUT_DIRECTORY="`pwd`"; \
-	export PREDEFINED="@BACKEND_DEFINES@"; \
+	export PREDEFINED="@BACKEND_DEFINES@ ENABLE_UNIT_TESTS ENABLE_INTEGRATION_TESTS"; \
+	export CLIENT_LIBRARY="@FUNAMBOL_SUBDIR@/test @FUNAMBOL_SUBDIR@/include "; \
+	export STRIP_FROM_PATH="$(srcdir) `dirname @FUNAMBOL_SUBDIR@`"; \
 	cd $(srcdir); doxygen
 clean-local: clean-html
 clean-html:
diff --git a/src/README.h b/src/README.h
new file mode 100644
index 00000000..78554d3d
--- /dev/null
+++ b/src/README.h
@@ -0,0 +1,19 @@
+/**
+ * @mainpage Getting Started
+ *
+ * This documentation for SyncEvolution and the Funambol C++ Client
+ * API was generated automatically from the source code.
+ *
+ * While most of the classes in SyncEvolution are documented, very
+ * little effort was spent on organizing this information in a coherent
+ * way. If you are a developer who wants to write a SyncML client based
+ * on the SyncEvolution framework, then you should have a look at
+ * the following classes:
+ * - TrackingSyncSource
+ * - EvolutionSyncSource
+ * - RegisterSyncSource
+ *
+ * The following classes help with testing your derived classes:
+ * - RegisterSyncSourceTest
+ * - ClientTest
+ */
diff --git a/src/core/EvolutionSyncSource.h b/src/core/EvolutionSyncSource.h
index c7c0775f..7fa6c85d 100644
--- a/src/core/EvolutionSyncSource.h
+++ b/src/core/EvolutionSyncSource.h
@@ -271,13 +271,13 @@ class TestRegistry : public vector<const RegisterSyncSourceTest *>
  * SyncEvolution accesses all sources through this interface.  This
  * class also implements common functionality for all SyncSources:
  * - handling of change IDs and URI
- * - finding the calender/contact backend
+ * - finding the calender/contact backend (only for Evolution)
  * - default implementation of SyncSource interface
  *
  * The default interface assumes that the backend's
- * open() already finds all items as well as new/modified/deleted
+ * beginSyncThrow() finds all items as well as new/modified/deleted
  * ones and stores their UIDs in the respective lists.
- * Then the SyncItem iterators just walk through these lists,
+ * Then the Items iterators just walk through these lists,
  * creating new items via createItem().
  *
  * Error reporting is done via the Log class and this instance
diff --git a/src/core/SyncEvolutionConfig.h b/src/core/SyncEvolutionConfig.h
index eb6ecd29..23480f4b 100644
--- a/src/core/SyncEvolutionConfig.h
+++ b/src/core/SyncEvolutionConfig.h
@@ -32,6 +32,11 @@
 #include <set>
 using namespace std;
 
+/**
+ * @defgroup ConfigHandling Configuration Handling
+ * @{
+ */
+
 class EvolutionSyncSourceConfig;
 class PersistentEvolutionSyncSourceConfig;
 class ConfigTree;
@@ -608,14 +613,13 @@ class EvolutionSyncConfig : public AbstractSyncConfig {
               const set<string> *sourceFilter);
 
     /**
-     * @defgroup SyncEvolutionSettings
+     * @name Settings specific to SyncEvolution
      *
-     * See etc/syncml-config.txt and the property definitions in
-     * SyncEvolutionConfig.cpp for the user-visible explanations of
+     * See the property definitions in SyncEvolutionConfig.cpp
+     * for the user-visible explanations of
      * these settings.
-     *
-     * @{
      */
+    /**@{*/
 
     virtual const char *getLogDir() const;
     virtual void setLogDir(const string &value, bool temporarily = false);
@@ -629,29 +633,17 @@ class EvolutionSyncConfig : public AbstractSyncConfig {
     /**@}*/
 
     /**
-     * @defgroup AbstractSyncConfig
+     * @name Settings inherited from Funambol
      *
      * These settings are required by the Funambol C++ client library.
      * Some of them are hard-coded in this class. A derived class could
      * make them configurable again, should that be desired.
-     *
-     * @{
      */
+    /**@{*/
 
-    /**
-     * @defgroup ActiveSyncSources
-     *
-     * This group of calls grants access to all active sources. In
-     * SyncEvolution the EvolutionSyncClient class decides which
-     * sources are active and thus fully configured and reimplements
-     * these calls.
-     *
-     * @{
-     */
     virtual AbstractSyncSourceConfig* getAbstractSyncSourceConfig(const char* name) const { return NULL; }
     virtual AbstractSyncSourceConfig* getAbstractSyncSourceConfig(unsigned int i) const { return NULL; }
     virtual unsigned int getAbstractSyncSourceConfigsCount() const { return 0; }
-    /**@}*/
 
     virtual const char*  getUsername() const;
     virtual void setUsername(const string &value, bool temporarily = false);
@@ -824,10 +816,10 @@ class EvolutionSyncSourceConfig : public AbstractSyncSourceConfig {
     bool exists() const { return m_nodes.m_configNode->exists(); }
 
     /**
-     * @defgroup EvolutionSyncSourceConfigExtensions
-     *
-     * @{
+     * @name Settings specific to SyncEvolution SyncSources
      */
+    /**@{*/
+
     virtual const char *getUser() const;
     virtual void setUser(const string &value, bool temporarily = false);
 
@@ -839,7 +831,6 @@ class EvolutionSyncSourceConfig : public AbstractSyncSourceConfig {
 
     virtual const char *getDatabaseID() const;
     virtual void setDatabaseID(const string &value, bool temporarily = false);
-    /**@}*/
 
     /**
      * Returns the data source type configured as part of the given
@@ -863,15 +854,9 @@ class EvolutionSyncSourceConfig : public AbstractSyncSourceConfig {
     /**@}*/
 
     /**
-     * @defgroup AbstractSyncSourceConfigAPI_not_yet_implemented
-     *
-     * These calls have to be implemented by EvolutionSyncSource
-     * instances. Some sources support more than one type. The
-     * configuration then selects the preferred format in
-     * the getSourceType() string.
-     * 
-     * @{
+     * @name Calls which have to be implemented by each EvolutionSyncSource.
      */
+    /**@{*/
 
     /**
      * Returns the preferred mime type of the items handled by the sync source.
@@ -897,13 +882,9 @@ class EvolutionSyncSourceConfig : public AbstractSyncSourceConfig {
     /**@}*/
 
     /**
-     * @defgroup AbstractSyncSourceConfigAPI_implemented
-     * @{
+     * @name Calls which usually do not have to be implemented by each EvolutionSyncSource.
      */
-    virtual const char *getType() const { return getMimeType(); }
-    virtual const char *getVersion() const { return getMimeVersion(); }
-    virtual const char*  getName() const { return m_name.c_str(); }
-    /**@}*/
+    /**@{*/
 
     /**
      * Returns the SyncSource URI: used in SyncML to address the data
@@ -983,6 +964,15 @@ class EvolutionSyncSourceConfig : public AbstractSyncSourceConfig {
 
     /**@}*/
 
+    /**
+     * @name Calls implemented by SyncEvolution.
+     */
+    /**@{*/
+    virtual const char *getType() const { return getMimeType(); }
+    virtual const char *getVersion() const { return getMimeVersion(); }
+    virtual const char*  getName() const { return m_name.c_str(); }
+    /**@}*/
+
  private:
     string m_name;
     SyncSourceNodes m_nodes;
@@ -1004,4 +994,6 @@ class PersistentEvolutionSyncSourceConfig : public EvolutionSyncSourceConfig {
     virtual const char* getSupportedTypes() const { return ""; }
 };
 
+/**@}*/
+
 #endif