From 4d604756dde24afa816eccb133788d624e74f14c Mon Sep 17 00:00:00 2001 From: Daniel Burrows Date: Wed, 21 Jul 2010 23:25:51 -0700 Subject: Tweak (hopefully improve) the package pool doccomments. --- src/qt/package_pool.h | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) (limited to 'src') diff --git a/src/qt/package_pool.h b/src/qt/package_pool.h index 284f75fa..e2c0fede 100644 --- a/src/qt/package_pool.h +++ b/src/qt/package_pool.h @@ -37,13 +37,14 @@ namespace aptitude class package; typedef boost::shared_ptr package_ptr; - /** \brief Class containig pointers to all used packages from cache. + /** \brief A global pool of package objects. * - * This class is responsible for responsing to cache events. It creates - * local container containing pointers to all package class objects, which - * for example are later used by packages_model class. + * The pool is filled when the object is created or when the + * cache is (re)loaded, and it is emptied when the cache is + * closed. * - * This class also propagates information about changing cache state + * This pool also interprets signals for the benefit of its + * client code. */ class package_pool { @@ -57,19 +58,41 @@ namespace aptitude /** \brief Return the globally unique instance of package_pool. */ static package_pool *get_instance(); - /** \brief Retrieve package count. */ + /** \brief Retrieve the number of packages in this pool. + * + * \return the number of package objects in this pool -- may + * not be equal to the PackageCount of the apt cache file, + * because some packages could be discarded in the pool. + */ virtual int get_packages_count() = 0; - /** \brief Retrieve a pointer to package at given index. */ + /** \brief Retrieve a pointer to the package at given index. + * + * \param index The zero-based index of the package. This is + * \e not equal to Pkg->ID. + * + * \return the package at index if index is between 0 and + * get_packages_count() - 1, and an invalid pointer otherwise. + */ virtual package_ptr get_package_at_index(unsigned int index) = 0; - /** \brief Register a slot to be invoked when the apt cache is reloaded. */ + /** \brief Register a slot to be invoked when the apt cache is reloaded. + * + * The slot is guaranteed to be invoked after the pool has + * been initialized from the new apt cache. + */ virtual sigc::connection connect_cache_reloaded(const sigc::slot &slot) = 0; - /** \brief Register a slot to be invoked when the apt cache is closed. */ + /** \brief Register a slot to be invoked when the apt cache is closed. + * + * The signal is guaranteed to be invoked before the pool of + * packages is emptied. + */ virtual sigc::connection connect_cache_closed(const sigc::slot &slot) = 0; - /** \brief Register a slot to be invoked when the state of packages changes. */ + /** \brief Register a slot to be invoked when the state of one + * or more packages changes. + */ virtual sigc::connection connect_cache_state_changed(const sigc::slot > &slot) = 0; }; } -- cgit v1.2.3