5 files changed, 187 insertions, 9 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
@@ -1,36 +1,89 @@
 #ifndef OPIE_PIM_ACCESS_BACKEND
 #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>
 OPimAccessBackend<T>::OPimAccessBackend() {
 }
 template <class T>
 OPimAccessBackend<T>::~OPimAccessBackend() {
 }
 #endif
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
@@ -1,118 +1,191 @@
 #ifndef OPIE_PIM_ACCESS_TEMPLATE_H
 #define OPIE_PIM_ACCESS_TEMPLATE_H
 #include <qarray.h>
 #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
+     * if the resource was changed externally
-     * QArray<int> ids
+     */
+    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>
 OPimAccessTemplate<T>::OPimAccessTemplate( BackEnd* end )
    : OTemplateBase<T>(), m_backEnd( end )
 {
 }
 template <class T>
 OPimAccessTemplate<T>::~OPimAccessTemplate() {
    qWarning("~OPimAccessTemplate<T>");
    delete m_backEnd;
 }
 template <class T>
 void OPimAccessTemplate<T>::load() {
    m_backEnd->load();
 }
 template <class T>
 void OPimAccessTemplate<T>::reload() {
    m_backEnd->reload();
 }
 template <class T>
 void OPimAccessTemplate<T>::save() {
    m_backEnd->save();
 }
 template <class T>
 OPimAccessTemplate<T>::List OPimAccessTemplate<T>::allRecords()const {
    QArray<int> ints = m_backEnd->allRecords();
    List lis(ints, this );
    return lis;
 }
 template <class T>
 OPimAccessTemplate<T>::List
 OPimAccessTemplate<T>::queryByExample( const T& t, int sortOrder ) {
    QArray<int> ints = m_backEnd->queryByExample( t, sortOrder );
    List lis(ints, this );
    return lis;
 }
 template <class T>
 T OPimAccessTemplate<T>::find( int uid ) {
    T t = m_backEnd->find( uid );
    return t;
 }
 template <class T>
 void OPimAccessTemplate<T>::clear() {
    invalidateCache();
    m_backEnd->clear();
 }
 template <class T>
 bool OPimAccessTemplate<T>::add( const T& t ) {
    return m_backEnd->add( t );
 }
 template <class T>
 bool OPimAccessTemplate<T>::remove( const T& t ) {
    return m_backEnd->remove( t.uid() );
 }
 template <class T>
 bool OPimAccessTemplate<T>::remove( int uid ) {
    return m_backEnd->remove( uid );
 }
 template <class T>
 bool OPimAccessTemplate<T>::replace( const T& t ) {
    return m_backEnd->replace( t );
 }
 template <class T>
 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
@@ -1,120 +1,133 @@
 #ifndef OPIE_PIM_RECORD_H
 #define OPIE_PIM_RECORD_H
 #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();
    /**
     * copy c'tor
     */
    OPimRecord( const OPimRecord& rec );
    /**
     * copy operator
     */
    OPimRecord &operator=( const OPimRecord& );
    /**
     * category names resolved
     */
    QStringList categoryNames()const;
    /**
     * set category names they will be resolved
     */
    void setCategoryNames( const QStringList& );
    /**
     * addCategoryName adds a name
     * 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
     */
    virtual QString toRichText()const = 0;
    /**
     * a small one line summary
     */
    virtual QString toShortText()const = 0;
    /**
     * the name of the Record
     */
    virtual QString type()const = 0;
    /**
     * converts the internal structure to a map
     */
    virtual QMap<int, QString> toMap()const = 0;
    /**
     * key value representation of extra items
     */
    virtual QMap<QString, QString> toExtraMap()const = 0;
    /**
     * the name for a recordField
     */
    virtual QString recordField(int)const = 0;
    /**
     * the related apps names
     */
    QStringList relatedApps()const;
    /**
     * 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;
 private:
    class OPimRecordPrivate;
    OPimRecordPrivate *d;
    QMap<QString, QArray<int> > m_relations;
    static Qtopia::UidGen m_uidGen;
 };
 #endif
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
@@ -1,165 +1,201 @@
 #ifndef OPIE_RECORD_LIST_H
 #define OPIE_RECORD_LIST_H
 #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 );
 private:
    QArray<int> m_uids;
    int m_current;
    const Base* m_temp;
    bool m_end : 1;
    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:
    QArray<int> m_ids;
    const Base* m_acc;
 };
 /* ok now implement it  */
 template <class T>
 ORecordListIterator<T>::ORecordListIterator() {
    m_current = 0;
    m_temp = 0l;
    m_end = true;
 }
 template <class T>
 ORecordListIterator<T>::~ORecordListIterator() {
 /* nothing to delete */
 }
 template <class T>
 ORecordListIterator<T>::ORecordListIterator( const ORecordListIterator<T>& it) {
    m_uids = it.m_uids;
    m_current = it.m_current;
    m_temp = it.m_temp;
    m_end = it.m_end;
    m_record = it.m_record;
 }
 template <class T>
 ORecordListIterator<T> &ORecordListIterator<T>::operator=( const ORecordListIterator<T>& it) {
    m_uids = it.m_uids;
    m_current = it.m_current;
    m_temp = it.m_temp;
    m_end = it.m_end;
    m_record = it.m_record;
    return *this;
 }
 template <class T>
 T &ORecordListIterator<T>::operator*() {
    if (!m_end )
        m_record = m_temp->find( m_uids[m_current] );
    else
        m_record = T();
    return m_record;
 }
 template <class T>
 ORecordListIterator<T> &ORecordListIterator<T>::operator++() {
    if (m_current < m_uids.count() ) {
        m_end = false;
        ++m_current;
    }else
        m_end = true;
    return *this;
 }
 template <class T>
 ORecordListIterator<T> &ORecordListIterator<T>::operator--() {
    if ( m_current > 0 ) {
        --m_current;
        m_end = false;
    }  else
        m_end = true;
    return *this;
 }
 template <class T>
 bool ORecordListIterator<T>::operator==( const ORecordListIterator<T>& it ) {
    /* if both are at we're the same.... */
    if ( m_end == it.m_end ) return true;
    if ( m_uids != it.m_uids ) return false;
    if ( m_current != it.m_current ) return false;
    if ( m_temp != it.m_temp ) return false;
    return true;
 }
 template <class T>
 bool ORecordListIterator<T>::operator!=( const ORecordListIterator<T>& it ) {
    return !(*this == it );
 }
 template <class T>
 ORecordListIterator<T>::ORecordListIterator( const QArray<int> uids,
                                  const Base* t )
    : m_uids( uids ), m_current( 0 ),  m_temp( t ), m_end( false )
 {
 }
 template <class T>
 ORecordList<T>::ORecordList( const QArray<int>& ids,
                             const Base* acc )
    : m_ids( ids ), m_acc( acc )
 {
 }
 template <class T>
 ORecordList<T>::~ORecordList() {
 /* nothing to do here */
 }
 template <class T>
 ORecordList<T>::Iterator ORecordList<T>::begin() {
    Iterator it( m_ids, m_acc );
    return it;
 }
 template <class T>
 ORecordList<T>::Iterator ORecordList<T>::end() {
    Iterator it( m_ids, m_acc );
    it.m_end = true;
    it.m_current = m_ids.count();
 }
 #endif
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,18 +1,21 @@
 #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() {
    }
    virtual T find( int uid ) = 0;
 };
 #endif