From 9a7fca01b4b01ade8ea9eb1bddd7ce6962aa448d Mon Sep 17 00:00:00 2001 From: Patrick Ohly Date: Sat, 2 Aug 2008 17:48:17 +0000 Subject: [PATCH] cleaned up Doxygen documentation + included Funambol API git-svn-id: https://zeitsenke.de/svn/SyncEvolution/trunk@693 15ad00c4-1369-45f4-8270-35d70d36bdcd --- Doxyfile | 14 ++++---- Makefile-gen.am | 9 +++-- src/README.h | 19 ++++++++++ src/core/EvolutionSyncSource.h | 6 ++-- src/core/SyncEvolutionConfig.h | 66 +++++++++++++++------------------- 5 files changed, 65 insertions(+), 49 deletions(-) create mode 100644 src/README.h 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 * 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 using namespace std; +/** + * @defgroup ConfigHandling Configuration Handling + * @{ + */ + class EvolutionSyncSourceConfig; class PersistentEvolutionSyncSourceConfig; class ConfigTree; @@ -608,14 +613,13 @@ class EvolutionSyncConfig : public AbstractSyncConfig { const set *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