SVN commit 1217450 by skelly:

Add some comments from Christian Mollekopf

 M  +4 -1      entitytreemodel_p.cpp  
 M  +18 -0     entitytreemodel_p.h  


--- trunk/KDE/kdepimlibs/akonadi/entitytreemodel_p.cpp #1217449:1217450
@@ -1263,7 +1263,7 @@
   kDebug() << "GEN" << generalPopulation << noMimetypes << noResources;
   // Includes recursive trees. Lower levels are fetched in the onRowsInserted slot if
   // necessary.
-  // HACK: fix this for recursive listing if we filter on mimetypes that only exit deeper
+  // HACK: fix this for recursive listing if we filter on mimetypes that only exist deeper
   // in the hierarchy
   if ( ( m_collectionFetchStrategy == EntityTreeModel::FetchFirstLevelChildCollections && generalPopulation )
     /*|| ( m_collectionFetchStrategy == EntityTreeModel::FetchCollectionsRecursive )*/ ) {
@@ -1578,6 +1578,9 @@
   m_mimeChecker.setWantedMimeTypes( m_monitor->mimeTypesMonitored() );
 
   QList<Collection> list = m_monitor->collectionsMonitored();
+  // In case there is only a single collection monitored, we can use this 
+  // collection as root of the node tree, in all other cases 
+  // Collection::root() is used
   if ( list.size() == 1 )
     m_rootCollection = list.first();
   else
--- trunk/KDE/kdepimlibs/akonadi/entitytreemodel_p.h #1217449:1217450
@@ -114,6 +114,9 @@
   Entity::Id childAt( Collection::Id, int position, bool *ok ) const;
   Item getItem( Item::Id id ) const;
   void removeChildEntities( Collection::Id collectionId );
+  /**
+   * Fetch parent collections and insert this @p collection and its parents into the node tree
+   */
   void retrieveAncestors( const Akonadi::Collection& collection );
   void ancestorsFetched( const Akonadi::Collection::List& collectionList );
   void insertCollection( const Akonadi::Collection &collection, const Akonadi::Collection& parent );
@@ -121,6 +124,10 @@
 
   void beginResetModel();
   void endResetModel();
+  /**
+   * Start function for filling the Model, finds and fetches the root of the node tree
+   * Next relevant function for filling the model is startFirstListJob()
+   */
   void fillModel();
 
   ItemFetchJob* getItemFetchJob( const Collection &parent, const ItemFetchScope &scope ) const;
@@ -153,6 +160,17 @@
   QHash<Collection::Id, uint> m_collectionSyncProgress;
 
   void rootCollectionFetched( const Collection::List &list );
+
+  /**
+   * Called after the root collection was fetched by fillModel
+   *
+   * Initiates further fetching of collections depending on the monitored collections
+   * (in the monitor) and the m_collectionFetchStrategy.
+   *
+   * Further collections are either fetched directly with fetchCollections and
+   * fetchItems or, in case that collections or resources are monitored explicitly
+   * via fetchTopLevelCollections
+   */
   void startFirstListJob();
 
   void serverStarted();