Some documentation

and addition to OTodoAccess
overDue and effectiveTodos

10 files changed, 374 insertions, 18 deletions

diff --git a/libopie/pim/opimaccessbackend.h b/libopie/pim/opimaccessbackend.h
index 8e744e7..5707b58 100644
--- a/libopie/pim/opimaccessbackend.h
+++ b/libopie/pim/opimaccessbackend.h
@@ -2,26 +2,79 @@
 #define OPIE_PIM_ACCESS_BACKEND
 
 #include <qarray.h>
 
 #include <opie/opimrecord.h>
 
+
+/**
+ * OPimAccessBackend is the base class
+ * for all private backends
+ * it operates on OPimRecord as the base class
+ * and it's responsible for fast manipulating
+ * the resource the implementation takes care
+ *  of
+ */
 template <class T = OPimRecord>
 class OPimAccessBackend {
 public:
     OPimAccessBackend();
     virtual ~OPimAccessBackend();
+    
+    /**
+     * load the resource
+     */
     virtual void load() = 0;
+    
+    /**
+     * reload the resource
+     */
     virtual void reload() = 0;
+    
+    /**
+     * save the resource and
+     * all it's changes
+     */
     virtual void save() = 0;
+    
+    /**
+     * return an array of
+     * all available uids
+     */
     virtual QArray<int> allRecords()const = 0;
+    
+    /**
+     * queryByExample for T with the SortOrder
+     * sort
+     */
     virtual QArray<int> queryByExample( const T& t, int sort ) = 0;
+    
+    /**
+     * find the OPimRecord with uid @param uid
+     * returns T and T.isEmpty() if nothing was found
+     */
     virtual T find(int uid ) = 0;
+    
+    /**
+     * clear the back end
+     */
     virtual void clear() = 0;
+    
+    /**
+     * add T
+     */
     virtual bool add( const T& t ) = 0;
+    
+    /**
+     * remove
+     */
     virtual bool remove( int uid ) = 0;
+    
+    /**
+     * replace a record with T.uid()
+     */
     virtual bool replace( const T& t ) = 0;
 
 
 };
 
 template <class T>
diff --git a/libopie/pim/opimaccesstemplate.h b/libopie/pim/opimaccesstemplate.h
index e0708e1..36f5a99 100644
--- a/libopie/pim/opimaccesstemplate.h
+++ b/libopie/pim/opimaccesstemplate.h
@@ -6,41 +6,111 @@
 #include <opie/opimrecord.h>
 #include <opie/opimaccessbackend.h>
 #include <opie/orecordlist.h>
 
 #include "otemplatebase.h"
 
+/**
+ * Thats the frontend to our OPIE PIM
+ * Library. Either you want to use it's
+ * interface or you want to implement
+ * your own Access lib
+ * Just create a OPimRecord and inherit from 
+ * the plugins
+ */
+
 template <class T = OPimRecord >
 class OPimAccessTemplate : public OTemplateBase<T> {
 public:
     typedef ORecordList<T> List;
     typedef OPimAccessBackend<T> BackEnd;
+
+    /**
+     * our sort order
+     * should be safe explaining
+     */
+    enum SortOrder { WildCards = 0, IgnoreCase = 1,
+                     RegExp = 2, ExactMatch = 4 };
+
+    /**
+     * c'tor BackEnd
+     */
     OPimAccessTemplate( BackEnd* end);
     virtual ~OPimAccessTemplate();
+    
+    /**
+     * load from the backend
+     */
     virtual void load();
+    
+    /**
+     * reload from the backend
+     */
     virtual void reload();
+    
+    /**
+     * save to the backend 
+     */
     virtual void save();
 
-    /*
-     *do array to Records conversion
-     * QArray<int> ids
+    /**
+     * if the resource was changed externally
+     */
+    bool wasChangedExternally()const;
+    
+    /**
+     * return a List of records
+     * you can iterate over them
      */
     virtual List allRecords()const;
+    
+    /**
+     * queryByExample 
+     */
     virtual List queryByExample( const T& t, int sortOrder );
+    
+    /**
+     * find the OPimRecord uid
+     */
     virtual T find( int uid );
 
     /* invalidate cache here */
+    /**
+     * clears the backend and invalidates the backend
+     */
     virtual void clear() ;
+    
+    /**
+     * add T to the backend
+     */
     virtual bool add( const T& t ) ;
 
     /* only the uid matters */
+    /**
+     * remove T from the backend
+     */
     virtual bool remove( const T& t );
+    
+    /**
+     * remove the OPimRecord with uid
+     */
     virtual bool remove( int uid );
+    
+    /**
+     * replace T from backend
+     */
     virtual bool replace( const T& t) ;
 protected:
+    /**
+     * invalidate the cache
+     */
     void invalidateCache();
+    
+    /**
+     * returns the backend
+     */
     BackEnd* backEnd();
     BackEnd* m_backEnd;
 
 };
 
 template <class T>
@@ -111,8 +181,11 @@ void OPimAccessTemplate<T>::invalidateCache() {
 
 }
 template <class T>
 OPimAccessTemplate<T>::BackEnd* OPimAccessTemplate<T>::backEnd() {
     return m_backEnd;
 }
-
+template <class T>
+bool OPimAccessTemplate<T>::wasChangedExternally()const {
+    return false;
+}
 #endif
diff --git a/libopie/pim/opimrecord.h b/libopie/pim/opimrecord.h
index e4d33d6..dbb94ed 100644
--- a/libopie/pim/opimrecord.h
+++ b/libopie/pim/opimrecord.h
@@ -4,15 +4,22 @@
 #include <qmap.h>
 #include <qstring.h>
 #include <qstringlist.h>
 
 #include <qpe/palmtoprecord.h>
 
+
+/**
+ * This is the base class for 
+ * all PIM Records
+ *
+ */
 class OPimRecord : public Qtopia::Record {
 public:
     /**
+     * c'tor
      * uid of 0 isEmpty
      * uid of 1 will be assigned a new one
      */
     OPimRecord(int uid = 0);
     ~OPimRecord();
 
@@ -41,12 +48,13 @@ public:
      * to the internal category list
      */
     void addCategoryName( const QString& );
 
     /**
      * if a Record isEmpty
+     * it's empty if it's 0
      */
     virtual bool isEmpty()const;
 
     /**
      * toRichText summary
      */
@@ -85,25 +93,30 @@ public:
     /**
      * the realtions between an app
      */
     QArray<int> relations( const QString& app )const;
 
     /**
-     *
+     * clear the relations for all relations
+     * with app
      */
     void clearRelation( const QString& app );
 
     /**
-     *
+     * add a relation
      */
     void addRelation( const QString& app,  int id );
 
     /**
-     *
+     * set the relations for an app
      */
     void setRelations( const QString&, QArray<int> ids );
+    
+    /**
+     * set the uid
+     */
     virtual void setUid( int uid );
 
 protected:
     Qtopia::UidGen &uidGen();
     QString crossToString()const;
 
diff --git a/libopie/pim/orecordlist.h b/libopie/pim/orecordlist.h
index a3955b0..3b30a73 100644
--- a/libopie/pim/orecordlist.h
+++ b/libopie/pim/orecordlist.h
@@ -4,22 +4,43 @@
 
 #include <qarray.h>
 
 #include "otemplatebase.h"
 #include "opimrecord.h"
 
-
+/**
+ * Our List Iterator
+ * it behaves like STL or Qt
+ *
+ * for(it = list.begin(); it != list.end(); ++it )
+ *   doSomeCoolStuff( (*it) );
+ */
 template <class T = OPimRecord>
 class ORecordListIterator {
 public:
     typedef OTemplateBase<T> Base;
+    
+    /**
+     * The c'tor used internally from
+     * ORecordList
+     */
     ORecordListIterator( const QArray<int>, const Base* );
+    
+    /**
+     * The standard c'tor
+     */
     ORecordListIterator();
     ~ORecordListIterator();
+    
     ORecordListIterator( const ORecordListIterator& );
     ORecordListIterator &operator=(const ORecordListIterator& );
+    
+    /**
+     * a * operator ;) 
+     * use it like this T = (*it);
+     */
     T &operator*();
     ORecordListIterator &operator++();
     ORecordListIterator &operator--();
 
     bool operator==( const ORecordListIterator& it );
     bool operator!=( const ORecordListIterator& it );
@@ -32,22 +53,37 @@ private:
     T m_record;
 
     /* d pointer for future versions */
     class IteratorPrivate;
     IteratorPrivate *d;
 };
-
+/**
+ * The recordlist used as a return type
+ * from OPimAccessTemplate
+ */ 
 template <class T = OPimRecord >
 class ORecordList {
 public:
     typedef OTemplateBase<T> Base;
     typedef ORecordListIterator<T> Iterator;
+    
+    /** 
+     * c'tor
+     */
     ORecordList( const QArray<int>& ids,
                  const Base* );
     ~ORecordList();
+    
+    /**
+     * the first iterator
+     */
     Iterator begin();
+    
+    /**
+     * the end
+     */
     Iterator end();
     /*
       ConstIterator begin()const;
       ConstIterator end()const;
     */
 private:
diff --git a/libopie/pim/otemplatebase.h b/libopie/pim/otemplatebase.h
index 41cc934..add1de4 100644
--- a/libopie/pim/otemplatebase.h
+++ b/libopie/pim/otemplatebase.h
@@ -1,11 +1,14 @@
 #ifndef OPIE_TEMPLATE_BASE_H
 #define OPIE_TEMPLATE_BASE_H
 
 #include "opimrecord.h"
 
+/**
+ * internal template base
+ */
 template <class T = OPimRecord>
 class OTemplateBase {
 public:
     OTemplateBase() {
     };
     virtual ~OTemplateBase() {
diff --git a/libopie2/opiepim/backend/opimaccessbackend.h b/libopie2/opiepim/backend/opimaccessbackend.h
index 8e744e7..5707b58 100644
--- a/libopie2/opiepim/backend/opimaccessbackend.h
+++ b/libopie2/opiepim/backend/opimaccessbackend.h
@@ -2,26 +2,79 @@
 #define OPIE_PIM_ACCESS_BACKEND
 
 #include <qarray.h>
 
 #include <opie/opimrecord.h>
 
+
+/**
+ * OPimAccessBackend is the base class
+ * for all private backends
+ * it operates on OPimRecord as the base class
+ * and it's responsible for fast manipulating
+ * the resource the implementation takes care
+ *  of
+ */
 template <class T = OPimRecord>
 class OPimAccessBackend {
 public:
     OPimAccessBackend();
     virtual ~OPimAccessBackend();
+    
+    /**
+     * load the resource
+     */
     virtual void load() = 0;
+    
+    /**
+     * reload the resource
+     */
     virtual void reload() = 0;
+    
+    /**
+     * save the resource and
+     * all it's changes
+     */
     virtual void save() = 0;
+    
+    /**
+     * return an array of
+     * all available uids
+     */
     virtual QArray<int> allRecords()const = 0;
+    
+    /**
+     * queryByExample for T with the SortOrder
+     * sort
+     */
     virtual QArray<int> queryByExample( const T& t, int sort ) = 0;
+    
+    /**
+     * find the OPimRecord with uid @param uid
+     * returns T and T.isEmpty() if nothing was found
+     */
     virtual T find(int uid ) = 0;
+    
+    /**
+     * clear the back end
+     */
     virtual void clear() = 0;
+    
+    /**
+     * add T
+     */
     virtual bool add( const T& t ) = 0;
+    
+    /**
+     * remove
+     */
     virtual bool remove( int uid ) = 0;
+    
+    /**
+     * replace a record with T.uid()
+     */
     virtual bool replace( const T& t ) = 0;
 
 
 };
 
 template <class T>
diff --git a/libopie2/opiepim/core/opimaccesstemplate.h b/libopie2/opiepim/core/opimaccesstemplate.h
index e0708e1..36f5a99 100644
--- a/libopie2/opiepim/core/opimaccesstemplate.h
+++ b/libopie2/opiepim/core/opimaccesstemplate.h
@@ -6,41 +6,111 @@
 #include <opie/opimrecord.h>
 #include <opie/opimaccessbackend.h>
 #include <opie/orecordlist.h>
 
 #include "otemplatebase.h"
 
+/**
+ * Thats the frontend to our OPIE PIM
+ * Library. Either you want to use it's
+ * interface or you want to implement
+ * your own Access lib
+ * Just create a OPimRecord and inherit from 
+ * the plugins
+ */
+
 template <class T = OPimRecord >
 class OPimAccessTemplate : public OTemplateBase<T> {
 public:
     typedef ORecordList<T> List;
     typedef OPimAccessBackend<T> BackEnd;
+
+    /**
+     * our sort order
+     * should be safe explaining
+     */
+    enum SortOrder { WildCards = 0, IgnoreCase = 1,
+                     RegExp = 2, ExactMatch = 4 };
+
+    /**
+     * c'tor BackEnd
+     */
     OPimAccessTemplate( BackEnd* end);
     virtual ~OPimAccessTemplate();
+    
+    /**
+     * load from the backend
+     */
     virtual void load();
+    
+    /**
+     * reload from the backend
+     */
     virtual void reload();
+    
+    /**
+     * save to the backend 
+     */
     virtual void save();
 
-    /*
-     *do array to Records conversion
-     * QArray<int> ids
+    /**
+     * if the resource was changed externally
+     */
+    bool wasChangedExternally()const;
+    
+    /**
+     * return a List of records
+     * you can iterate over them
      */
     virtual List allRecords()const;
+    
+    /**
+     * queryByExample 
+     */
     virtual List queryByExample( const T& t, int sortOrder );
+    
+    /**
+     * find the OPimRecord uid
+     */
     virtual T find( int uid );
 
     /* invalidate cache here */
+    /**
+     * clears the backend and invalidates the backend
+     */
     virtual void clear() ;
+    
+    /**
+     * add T to the backend
+     */
     virtual bool add( const T& t ) ;
 
     /* only the uid matters */
+    /**
+     * remove T from the backend
+     */
     virtual bool remove( const T& t );
+    
+    /**
+     * remove the OPimRecord with uid
+     */
     virtual bool remove( int uid );
+    
+    /**
+     * replace T from backend
+     */
     virtual bool replace( const T& t) ;
 protected:
+    /**
+     * invalidate the cache
+     */
     void invalidateCache();
+    
+    /**
+     * returns the backend
+     */
     BackEnd* backEnd();
     BackEnd* m_backEnd;
 
 };
 
 template <class T>
@@ -111,8 +181,11 @@ void OPimAccessTemplate<T>::invalidateCache() {
 
 }
 template <class T>
 OPimAccessTemplate<T>::BackEnd* OPimAccessTemplate<T>::backEnd() {
     return m_backEnd;
 }
-
+template <class T>
+bool OPimAccessTemplate<T>::wasChangedExternally()const {
+    return false;
+}
 #endif
diff --git a/libopie2/opiepim/core/opimrecord.h b/libopie2/opiepim/core/opimrecord.h
index e4d33d6..dbb94ed 100644
--- a/libopie2/opiepim/core/opimrecord.h
+++ b/libopie2/opiepim/core/opimrecord.h
@@ -4,15 +4,22 @@
 #include <qmap.h>
 #include <qstring.h>
 #include <qstringlist.h>
 
 #include <qpe/palmtoprecord.h>
 
+
+/**
+ * This is the base class for 
+ * all PIM Records
+ *
+ */
 class OPimRecord : public Qtopia::Record {
 public:
     /**
+     * c'tor
      * uid of 0 isEmpty
      * uid of 1 will be assigned a new one
      */
     OPimRecord(int uid = 0);
     ~OPimRecord();
 
@@ -41,12 +48,13 @@ public:
      * to the internal category list
      */
     void addCategoryName( const QString& );
 
     /**
      * if a Record isEmpty
+     * it's empty if it's 0
      */
     virtual bool isEmpty()const;
 
     /**
      * toRichText summary
      */
@@ -85,25 +93,30 @@ public:
     /**
      * the realtions between an app
      */
     QArray<int> relations( const QString& app )const;
 
     /**
-     *
+     * clear the relations for all relations
+     * with app
      */
     void clearRelation( const QString& app );
 
     /**
-     *
+     * add a relation
      */
     void addRelation( const QString& app,  int id );
 
     /**
-     *
+     * set the relations for an app
      */
     void setRelations( const QString&, QArray<int> ids );
+    
+    /**
+     * set the uid
+     */
     virtual void setUid( int uid );
 
 protected:
     Qtopia::UidGen &uidGen();
     QString crossToString()const;
 
diff --git a/libopie2/opiepim/core/otemplatebase.h b/libopie2/opiepim/core/otemplatebase.h
index 41cc934..add1de4 100644
--- a/libopie2/opiepim/core/otemplatebase.h
+++ b/libopie2/opiepim/core/otemplatebase.h
@@ -1,11 +1,14 @@
 #ifndef OPIE_TEMPLATE_BASE_H
 #define OPIE_TEMPLATE_BASE_H
 
 #include "opimrecord.h"
 
+/**
+ * internal template base
+ */
 template <class T = OPimRecord>
 class OTemplateBase {
 public:
     OTemplateBase() {
     };
     virtual ~OTemplateBase() {
diff --git a/libopie2/opiepim/orecordlist.h b/libopie2/opiepim/orecordlist.h
index a3955b0..3b30a73 100644
--- a/libopie2/opiepim/orecordlist.h
+++ b/libopie2/opiepim/orecordlist.h
@@ -4,22 +4,43 @@
 
 #include <qarray.h>
 
 #include "otemplatebase.h"
 #include "opimrecord.h"
 
-
+/**
+ * Our List Iterator
+ * it behaves like STL or Qt
+ *
+ * for(it = list.begin(); it != list.end(); ++it )
+ *   doSomeCoolStuff( (*it) );
+ */
 template <class T = OPimRecord>
 class ORecordListIterator {
 public:
     typedef OTemplateBase<T> Base;
+    
+    /**
+     * The c'tor used internally from
+     * ORecordList
+     */
     ORecordListIterator( const QArray<int>, const Base* );
+    
+    /**
+     * The standard c'tor
+     */
     ORecordListIterator();
     ~ORecordListIterator();
+    
     ORecordListIterator( const ORecordListIterator& );
     ORecordListIterator &operator=(const ORecordListIterator& );
+    
+    /**
+     * a * operator ;) 
+     * use it like this T = (*it);
+     */
     T &operator*();
     ORecordListIterator &operator++();
     ORecordListIterator &operator--();
 
     bool operator==( const ORecordListIterator& it );
     bool operator!=( const ORecordListIterator& it );
@@ -32,22 +53,37 @@ private:
     T m_record;
 
     /* d pointer for future versions */
     class IteratorPrivate;
     IteratorPrivate *d;
 };
-
+/**
+ * The recordlist used as a return type
+ * from OPimAccessTemplate
+ */ 
 template <class T = OPimRecord >
 class ORecordList {
 public:
     typedef OTemplateBase<T> Base;
     typedef ORecordListIterator<T> Iterator;
+    
+    /** 
+     * c'tor
+     */
     ORecordList( const QArray<int>& ids,
                  const Base* );
     ~ORecordList();
+    
+    /**
+     * the first iterator
+     */
     Iterator begin();
+    
+    /**
+     * the end
+     */
     Iterator end();
     /*
       ConstIterator begin()const;
       ConstIterator end()const;
     */
 private: