More API doc

QString -> const QString&
QString = 0l -> QString::null

8 files changed, 134 insertions, 11 deletions

diff --git a/libopie2/opiepim/backend/obackendfactory.h b/libopie2/opiepim/backend/obackendfactory.h
index 3a73210..ad6cf5a 100644
--- a/libopie2/opiepim/backend/obackendfactory.h
+++ b/libopie2/opiepim/backend/obackendfactory.h
@@ -16,6 +16,11 @@
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.6  2003/04/13 18:07:10  zecke
+ * More API doc
+ * QString -> const QString&
+ * QString = 0l -> QString::null
+ *
  * Revision 1.5  2003/02/21 23:31:52  zecke
  * Add XML datebookresource
  * -clean up todoaccessxml header
@@ -63,7 +68,21 @@
 #include "otodoaccesssql.h"
 #endif
 
-
+/**
+ * This class is our factory. It will give us the default implementations
+ * of at least Todolist, Contacts and Datebook. In the future this class will
+ * allow users to switch the backend with ( XML->SQLite ) without the need
+ * to recompile.#
+ * This class as the whole PIM Api is making use of templates
+ *
+ * <pre>
+ *   OTodoAccessBackend* backend = OBackEndFactory<OTodoAccessBackend>::Default("todo", QString::null );
+ *   backend->load();
+ * </pre>
+ *
+ * @author Stefan Eilers
+ * @version 0.1
+ */
 template<class T>
 class OBackendFactory
 {
@@ -76,6 +95,11 @@ class OBackendFactory
                 DATE
         };
 
+        /**
+         * Returns a backend implementation for backendName
+         * @param backendName the type of the backend
+         * @param appName will be passed on to the backend
+         */
         static T* Default( const QString backendName, const QString& appName ){
 
                 // __asm__("int3");
diff --git a/libopie2/opiepim/backend/ocontactaccessbackend.h b/libopie2/opiepim/backend/ocontactaccessbackend.h
index 821f5bf..ebeb42d 100644
--- a/libopie2/opiepim/backend/ocontactaccessbackend.h
+++ b/libopie2/opiepim/backend/ocontactaccessbackend.h
@@ -19,6 +19,11 @@
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.5  2003/04/13 18:07:10  zecke
+ * More API doc
+ * QString -> const QString&
+ * QString = 0l -> QString::null
+ *
  * Revision 1.4  2002/11/13 14:14:51  eilers
  * Added sorted for Contacts..
  *
@@ -44,15 +49,26 @@
 #include "ocontact.h"
 #include "opimaccessbackend.h"
 
-#include "qregexp.h"
+#include <qregexp.h>
 
+/**
+ * This class represents the interface of all Contact Backends.
+ * Derivates of this class will be used to access the contacts.
+ * As implementation currently XML and vCard exist. This class needs to be implemented
+ * if you want to provide your own storage.
+ * In all queries a list of uids is passed on instead of loading the actual record!
+ *
+ * @see OContactAccessBackend_VCard
+ * @see OContactAccessBackend_XML
+ */
 class OContactAccessBackend: public OPimAccessBackend<OContact> {
  public:
         OContactAccessBackend() {}
         virtual ~OContactAccessBackend() {}
 
 
-        /** Return if database was changed externally.
+        /**
+         * Return if database was changed externally.
          * This may just make sense on file based databases like a XML-File.
          * It is used to prevent to overwrite the current database content
          * if the file was already changed by something else !
@@ -68,17 +84,23 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> {
 
         virtual QArray<int> matchRegexp(  const QRegExp &r ) const = 0;
 
-        /** Return all possible settings.
+        /**
+         *  Return all possible settings.
          *  @return All settings provided by the current backend
          * (i.e.: query_WildCards & query_IgnoreCase)
          */
         virtual const uint querySettings() = 0;
 
-        /** Check whether settings are correct.
+        /**
+         * Check whether settings are correct.
          * @return <i>true</i> if the given settings are correct and possible.
          */
         virtual bool hasQuerySettings (uint querySettings) const = 0;
 
+        /**
+         * FIXME!!!
+         * Returns a sorted list of records either ascendinf or descending for a giving criteria and category
+         */
         virtual QArray<int> sorted( bool ascending, int sortOrder, int sortFilter, int cat ) = 0;
 
 };
diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp
index f24523f..270bef3 100644
--- a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp
+++ b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp
@@ -17,6 +17,11 @@
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.10  2003/04/13 18:07:10  zecke
+ * More API doc
+ * QString -> const QString&
+ * QString = 0l -> QString::null
+ *
  * Revision 1.9  2003/03/21 10:33:09  eilers
  * Merged speed optimized xml backend for contacts to main.
  * Added QDateTime to querybyexample. For instance, it is now possible to get
@@ -76,7 +81,7 @@
 
 #include <qfile.h>
 
-OContactAccessBackend_VCard::OContactAccessBackend_VCard ( QString , QString filename ):
+OContactAccessBackend_VCard::OContactAccessBackend_VCard ( const QString& , const QString& filename ):
         m_dirty( false ),
         m_file( filename )
 {
diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h
index 93e2da3..712d769 100644
--- a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h
+++ b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h
@@ -17,6 +17,11 @@
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.6  2003/04/13 18:07:10  zecke
+ * More API doc
+ * QString -> const QString&
+ * QString = 0l -> QString::null
+ *
  * Revision 1.5  2003/03/21 10:33:09  eilers
  * Merged speed optimized xml backend for contacts to main.
  * Added QDateTime to querybyexample. For instance, it is now possible to get
@@ -47,9 +52,14 @@
 
 class VObject;
 
+/**
+ * This is the vCard 2.1 implementation of the Contact Storage
+ * @see OContactAccessBackend_XML
+ * @see OPimAccessBackend
+ */
 class OContactAccessBackend_VCard : public OContactAccessBackend {
  public:
-        OContactAccessBackend_VCard ( QString appname, QString filename = 0l );
+        OContactAccessBackend_VCard ( const QString& appname, const QString& filename = QString::null );
 
         bool load ();
         bool reload();
diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp b/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp
index c5a7820..661cd51 100644
--- a/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp
+++ b/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp
@@ -17,6 +17,11 @@
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.5  2003/04/13 18:07:10  zecke
+ * More API doc
+ * QString -> const QString&
+ * QString = 0l -> QString::null
+ *
  * Revision 1.4  2003/03/21 14:32:54  mickeyl
  * g++ compliance fix: default arguments belong into the declaration, but not the definition
  *
@@ -107,7 +112,7 @@
 using namespace Opie;
 
 
-OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString filename ):
+OContactAccessBackend_XML::OContactAccessBackend_XML ( const QString& appname, const QString& filename ):
         m_changed( false )
 {
         // Just m_contactlist should call delete if an entry
diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_xml.h b/libopie2/opiepim/backend/ocontactaccessbackend_xml.h
index 4d6a7ef..7b5365b 100644
--- a/libopie2/opiepim/backend/ocontactaccessbackend_xml.h
+++ b/libopie2/opiepim/backend/ocontactaccessbackend_xml.h
@@ -17,6 +17,11 @@
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.14  2003/04/13 18:07:10  zecke
+ * More API doc
+ * QString -> const QString&
+ * QString = 0l -> QString::null
+ *
  * Revision 1.13  2003/03/21 10:33:09  eilers
  * Merged speed optimized xml backend for contacts to main.
  * Added QDateTime to querybyexample. For instance, it is now possible to get
@@ -84,9 +89,14 @@
 #include <qdict.h>
 
 /* the default xml implementation */
+/**
+ * This class is the XML implementation of a Contact backend
+ * it does implement everything available for OContact.
+ * @see OPimAccessBackend for more information of available methods
+ */
 class OContactAccessBackend_XML : public OContactAccessBackend {
  public:
-        OContactAccessBackend_XML ( QString appname, QString filename = 0l );
+        OContactAccessBackend_XML ( const QString& appname, const QString& filename = QString::null );
         
         bool save();
         
diff --git a/libopie2/opiepim/backend/odatebookaccessbackend.h b/libopie2/opiepim/backend/odatebookaccessbackend.h
index eb6e8fb..86ff298 100644
--- a/libopie2/opiepim/backend/odatebookaccessbackend.h
+++ b/libopie2/opiepim/backend/odatebookaccessbackend.h
@@ -6,25 +6,66 @@
 #include "opimaccessbackend.h"
 #include "oevent.h"
 
+/**
+ * This class is the interface to the storage of Events.
+ * @see OPimAccessBackend
+ *
+ */
 class ODateBookAccessBackend : public OPimAccessBackend<OEvent> {
 public:
     typedef int UID;
+
+    /**
+     * c'tor without parameter
+     */
     ODateBookAccessBackend();
     ~ODateBookAccessBackend();
 
+    /**
+     * This method should return a list of UIDs containing
+     * all events. No filter should be applied
+     * @return list of events
+     */
     virtual QArray<UID> rawEvents()const = 0;
+
+    /**
+     * This method should return a list of UIDs containing
+     * all repeating events. No filter should be applied
+     * @return list of repeating events
+     */
     virtual QArray<UID> rawRepeats()const = 0;
+
+    /**
+     * This mthod should return a list of UIDs containing all non
+     * repeating events. No filter should be applied
+     * @return list of nonrepeating events
+     */
     virtual QArray<UID> nonRepeats() const = 0;
 
     /**
-     * these two methods are used if you do not implement
-     * effectiveEvents...
+     * If you do not want to implement the effectiveEvents methods below
+     * you need to supply it with directNonRepeats.
+     * This method can return empty lists if effectiveEvents is implememted
      */
     virtual OEvent::ValueList directNonRepeats() = 0;
+
+    /**
+     * Same as above but return raw repeats!
+     */
     virtual OEvent::ValueList directRawRepeats() = 0;
 
     /* is implemented by default but you can reimplement it*/
+    /**
+     * Effective Events are special event occuring during a time frame. This method does calcualte
+     * EffectiveEvents bases on the directNonRepeats and directRawRepeats. You may implement this method
+     * yourself
+     */
     virtual OEffectiveEvent::ValueList effecticeEvents( const QDate& from, const QDate& to );
+
+    /**
+     * this is an overloaded member function
+     * @see effecticeEvents
+     */
     virtual OEffectiveEvent::ValueList effecticeEvents( const QDateTime& start );
 
 };
diff --git a/libopie2/opiepim/backend/odatebookaccessbackend_xml.h b/libopie2/opiepim/backend/odatebookaccessbackend_xml.h
index 563c31f..7848f7c 100644
--- a/libopie2/opiepim/backend/odatebookaccessbackend_xml.h
+++ b/libopie2/opiepim/backend/odatebookaccessbackend_xml.h
@@ -5,6 +5,12 @@
 
 #include "odatebookaccessbackend.h"
 
+/**
+ * This is the default XML implementation for DateBoook XML storage
+ * It fully implements the interface
+ * @see ODateBookAccessBackend
+ * @see OPimAccessBackend
+ */
 class ODateBookAccessBackend_XML : public ODateBookAccessBackend {
 public:
     ODateBookAccessBackend_XML( const QString& appName,