3 files changed, 109 insertions, 38 deletions

diff --git a/libopie2/opiepim/core/ocontactaccess.h b/libopie2/opiepim/core/ocontactaccess.h
index 691ece2..bd85b4e 100644
--- a/libopie2/opiepim/core/ocontactaccess.h
+++ b/libopie2/opiepim/core/ocontactaccess.h
@@ -60,21 +60,38 @@ class OPimContactAccess: public QObject, public OPimAccessTemplate<OPimContact>
     Q_OBJECT
 
  public:
+    /**
+     * Filter for sorted()
+     * @see SortFilterBase in OPimBase
+     */
     enum SortFilter {
-        DoNotShowNoneChildren      = FilterCustom<<1,
-        DoNotShowNoneAnniversary   = FilterCustom<<2,
-        DoNotShowNoneBirthday      = FilterCustom<<3,
-        DoNotShowNoHomeAddress     = FilterCustom<<4,
-        DoNotShowNoBusinessAddress = FilterCustom<<5
+        /** Don't return entries who don't have children */
+        DoNotShowWithoutChildren        = FilterCustom<<1,
+        /** Don't return entries who don't have an anniversary */
+        DoNotShowWithoutAnniversary     = FilterCustom<<2,
+         /** Don't return entries who don't have a birthday */
+        DoNotShowWithoutBirthday        = FilterCustom<<3,
+         /** Don't return entries who don't have a home address */
+        DoNotShowWithoutHomeAddress     = FilterCustom<<4,
+        /** Don't return entries who don't have a business address */
+        DoNotShowWithoutBusinessAddress = FilterCustom<<5,
+        /** Don't return entries which hava any category */
+        DoNotShowWithCategory = FilterCustom << 6
     };
 
+    /**
+     * Sort order for sorted()
+     * @see SortOrderBase in OPimBase
+     */
     enum SortOrder {
         SortTitle = SortCustom,
         SortFirstName,
         SortMiddleName,
+        SortLastName,
         SortSuffix,
         SortEmail,
         SortNickname,
+        SortFileAsName,
         SortAnniversary,
         SortBirthday,
         SortGender
@@ -99,14 +116,18 @@ class OPimContactAccess: public QObject, public OPimAccessTemplate<OPimContact>
         ~OPimContactAccess ();
 
 
-        /** Return all possible settings.
+        /** 
+         * Return all possible settings for queryByExample().
          *  @return All settings provided by the current backend
-         * (i.e.: query_WildCards & query_IgnoreCase)
+         * (i.e.: WildCards & IgnoreCase)
+         * @see QuerySettings in OPimBase for details of the parameter
          */
         const uint querySettings();
 
-        /** Check whether settings are correct.
+        /** 
+         * Check whether settings are correct for queryByExample().
          * @return <i>true</i> if the given settings are correct and possible.
+         * @see QuerySettings in OPimBase for details of the parameter
          */
         bool hasQuerySettings ( int querySettings ) const;
 
diff --git a/libopie2/opiepim/core/opimaccesstemplate.h b/libopie2/opiepim/core/opimaccesstemplate.h
index 2deb92a..073d5f9 100644
--- a/libopie2/opiepim/core/opimaccesstemplate.h
+++ b/libopie2/opiepim/core/opimaccesstemplate.h
@@ -90,15 +90,52 @@ public:
     virtual T find( UID uid )const;
     virtual T find( UID uid, const QArray<int>&,
                     uint current, typename OTemplateBase<T>::CacheDirection dir = OTemplateBase<T>::Forward )const;
-    virtual List sorted( const List&, bool ascending, int sortOrder,
+    //@}
+
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param list of UID's received by allRecords() or others...
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cat number of category.
+     */
+    virtual List sorted( const List& list, bool ascending, int sortOrder,
                          int sortFilter, int cat )const;
-    virtual List sorted( const List&, bool ascending, int sortOrder,
+
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param list of UID's received by allRecords() or others...
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cats List of categories.
+     */
+    virtual List sorted( const List& list, bool ascending, int sortOrder,
                          int sortFilter, const QArray<UID>& cats )const;
+
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cat number of category.
+     */
     virtual List sorted( bool ascending, int sortOrder, int sortFilter, int cat )const;
-    virtual List sorted( bool ascending, int sortOrder, int sortOrder,
-                         const QArray<UID>& cats )const;
-    //@}
 
+    /** 
+     * Get sorted lists..
+     * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params:
+     * @param ascending Sort in ascending order if true, otherwise descending
+     * @param sortOrder Setting the sort order defined by enum SortOrder
+     * @param sortFilter Setting the sort filter defined by enum SortFilter
+     * @param cats List of categories.
+     */
+    virtual List sorted( bool ascending, int sortOrder, int sortFilter,
+                         const QArray<UID>& cats )const;
     /**
      * (Re)Implementation
      */
@@ -129,7 +166,6 @@ public:
     //@}
 
     void setReadAhead( uint count );
-    virtual T cacheFind( int uid )const;
     void cache( const T& )const;
     void setSaneCacheSize( int );
 
@@ -258,11 +294,6 @@ T OPimAccessTemplate<T>::find( UID uid ) const{
     return t;
 }
 
-template <class T>
-T OPimAccessTemplate<T>::cacheFind( int uid ) const
-{
-        return m_cache.find( uid );
-}
 
 /**
  * read ahead cache find method ;)
diff --git a/libopie2/opiepim/core/opimtemplatebase.h b/libopie2/opiepim/core/opimtemplatebase.h
index b238a68..c8abab4 100644
--- a/libopie2/opiepim/core/opimtemplatebase.h
+++ b/libopie2/opiepim/core/opimtemplatebase.h
@@ -80,6 +80,7 @@ struct OPimBase {
 
     //@{
     virtual QArray<UID> records()const = 0;
+    //@}
 
     /** Constants for query.
      * Use this constants to set the query parameters.
@@ -87,40 +88,58 @@ struct OPimBase {
      * @see queryByExample()
      */
     enum QuerySettings {
-        WildCards  = 0x0001, /** Use Wildcards */
-        IgnoreCase = 0x0002, /** Ignore the Case  */
-        RegExp     = 0x0004, /** Do a Regular Expression match */
-        ExactMatch = 0x0008, /** It needs to exactly match     */
-        MatchOne   = 0x0010, /** Only one Entry must match */
-        DateDiff   = 0x0020, /** Find all entries from today until given date */
-        DateYear   = 0x0040, /** The year matches */
-        DateMonth  = 0x0080, /** The month matches */
-        DateDay    = 0x0100, /** The day matches */
-        LastItem   = 0xffff  /** the last possible name */
+        /** Use Wildcards */
+        WildCards  = 0x0001,
+        /** Ignore the Case  */
+        IgnoreCase = 0x0002,
+        /** Do a Regular Expression match */
+        RegExp     = 0x0004, 
+        /** It needs to exactly match     */
+        ExactMatch = 0x0008, 
+        /** Only one Entry must match */
+        MatchOne   = 0x0010, 
+        /** Find all entries from today until given date */
+        DateDiff   = 0x0020, 
+        /** The year matches */
+        DateYear   = 0x0040, 
+        /** The month matches */
+        DateMonth  = 0x0080, 
+        /** The day matches */
+        DateDay    = 0x0100, 
+        /** The last possible name matches */
+        LastItem   = 0xffff  
     };
 
     /**
      * Common Attributes for the Sort Order
      */
     enum SortOrderBase {
-        SortSummary = 0,       /** Sort by a Summary of the records */
-        SortByCategory = 1,    /** Sort by Category */
-        SortByDate = 2,        /** Sort by Date */
-        SortCustom  = 10,      /** The First available sort number for the OPimAccessTemplates */
-        LastSortOrderBase = 0xffff /** make this enum 16bit large */
+        /** Sort by a Summary of the records */
+        SortSummary = 0,
+        /** Sort by Category */
+        SortByCategory = 1,
+        /** Sort by Date */
+        SortByDate = 2, 
+        /** The First available sort number for the OPimAccessTemplates */
+        SortCustom  = 10,
+        /** make this enum 16bit large */
+        LastSortOrderBase = 0xffff 
     };
 
     /**
-     * Sort with the help of the \sa sorted function
-     * a list of Items.
+     * Sort a list of Items with the help of the sorted() function.
      * The Item you provide in SortOrder will be used
      * for sorting.
      *
-     * @see sorted
+     * @see OPimAccessTemplate<>::sorted()
      */
     enum SortFilterBase {
+            /** Do not filter anything. */
+        FilterOff = 0,
+        /** Use given Categories for filter */
         FilterCategory = 1,
-        FilterCustom = 1024,
+        /** The first available custom filter defined in the specialized frontends */
+        FilterCustom = 1024, 
         LastSortFilterBase = 0xffffffff
     };