Doxygen updates

10 files changed, 165 insertions, 0 deletions

diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index 3afc5b740..388db4822 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -157,6 +157,31 @@
  * \ingroup Utility
  */
 
+/** \defgroup Iterator Iterator utilities
+ * Iterator utilities.
+ *
+ * Various adapter classes for iterators are provided to simplify writing code.
+ *
+ * \section IteratorImportant Important Classes
+ *
+ * Insert iterator adapters:
+ *
+ * - paludis::CreateInsertIterator (which can be created via
+ *   paludis::create_inserter) uses the inserted value to create an object.
+ * - paludis::FilterInsertIterator (which can be created via
+ *   paludis::filter_inserter) only inserts the object if a predicate is true.
+ * - paludis::TranslateInsertIterator (which can be created via
+ *   paludis::translate_inserter) performs a transformation upon the object to
+ *   be inserted.
+ *
+ * Input iterator adapters:
+ *
+ * - paludis::IndirectIterator removes one level of dereferencing when using a
+ *   container of pointer-like objects.
+ *
+ * \ingroup Utility
+ */
+
 /** \defgroup ConfigFile Configuration handling
  * Configuration handling.
  *
diff --git a/paludis/create_insert_iterator.hh b/paludis/create_insert_iterator.hh
index 2a3341c86..c5faaea15 100644
--- a/paludis/create_insert_iterator.hh
+++ b/paludis/create_insert_iterator.hh
@@ -26,6 +26,12 @@
 
 namespace paludis
 {
+    /**
+     * A CreateInsertIterator is an insert iterator that creates an object of
+     * the specified type using the provided value.
+     *
+     * \ingroup Iterator
+     */
     template <typename Iter_, typename Type_>
     class CreateInsertIterator :
         public std::iterator<typename std::iterator_traits<Iter_>::iterator_category, void, void, void, void>
@@ -100,6 +106,8 @@ namespace paludis
 
     /**
      * Convenience function: make a TranslateInsertIterator.
+     *
+     * \ingroup Iterator
      */
     template <typename Type_, typename Iter_>
     CreateInsertIterator<Iter_, Type_> create_inserter(const Iter_ & i)
diff --git a/paludis/default_config.hh b/paludis/default_config.hh
index 2c20eb809..b68dc8d0b 100644
--- a/paludis/default_config.hh
+++ b/paludis/default_config.hh
@@ -71,6 +71,10 @@ namespace paludis
 
     typedef MakeSmartRecord<UseConfigEntryTag>::Type UseConfigEntry;
 
+    /**
+     * DefaultConfig is used by DefaultEnvironment to access the user's
+     * configuration settings from on-disk configuration files.
+     */
     class DefaultConfig :
         public InstantiationPolicy<DefaultConfig, instantiation_method::SingletonAsNeededTag>
     {
@@ -101,21 +105,37 @@ namespace paludis
             std::vector<std::pair<UseFlagName, UseFlagState> > _default_use;
 
         public:
+            /**
+             * An iterator for our repositories.
+             */
             typedef std::list<RepositoryConfigEntry>::const_iterator RepositoryIterator;
 
+            /**
+             * Iterator to the start of our repositories.
+             */
             RepositoryIterator begin_repositories() const
             {
                 return _repos.begin();
             }
 
+            /**
+             * Iterator to past the end of our repositories.
+             */
             RepositoryIterator end_repositories() const
             {
                 return _repos.end();
             }
 
+            /**
+             * Iterate over our package.keywords entries.
+             */
             typedef std::vector<std::pair<PackageDepAtom::ConstPointer, KeywordName> >::const_iterator
                 PackageKeywordsIterator;
 
+            /**
+             * Iterator to the start of the package.keywords entries for a
+             * particular package.
+             */
             PackageKeywordsIterator begin_package_keywords(const QualifiedPackageName & d) const
             {
                 std::map<QualifiedPackageName, std::vector<
@@ -126,6 +146,10 @@ namespace paludis
                     return _empty_keywords.begin();
             }
 
+            /**
+             * Iterator to past the end of the package.keywords entries for a
+             * particular file.
+             */
             PackageKeywordsIterator end_package_keywords(const QualifiedPackageName & d) const
             {
                 std::map<QualifiedPackageName, std::vector<
@@ -136,21 +160,36 @@ namespace paludis
                     return _empty_keywords.end();
             }
 
+            /**
+             * Iterator over the default keywords entries.
+             */
             typedef std::vector<KeywordName>::const_iterator DefaultKeywordsIterator;
 
+            /**
+             * Iterator to the start of our default keywords entries.
+             */
             DefaultKeywordsIterator begin_default_keywords() const
             {
                 return _default_keywords.begin();
             }
 
+            /**
+             * Iterator to past the end of our default keywords entries.
+             */
             DefaultKeywordsIterator end_default_keywords() const
             {
                 return _default_keywords.end();
             }
 
+            /**
+             * Iterator over user package masks.
+             */
             typedef IndirectIterator<std::vector<PackageDepAtom::ConstPointer>::const_iterator,
                     const PackageDepAtom> UserMasksIterator;
 
+            /**
+             * Iterator to the start of the user package masks.
+             */
             UserMasksIterator begin_user_masks(const QualifiedPackageName & d) const
             {
                 std::map<QualifiedPackageName, std::vector<PackageDepAtom::ConstPointer> >::const_iterator r;
@@ -160,6 +199,9 @@ namespace paludis
                     return _empty_masks.begin();
             }
 
+            /**
+             * Iterator to past the end of the user package masks.
+             */
             UserMasksIterator end_user_masks(const QualifiedPackageName & d) const
             {
                 std::map<QualifiedPackageName, std::vector<PackageDepAtom::ConstPointer> >::const_iterator r;
@@ -169,9 +211,15 @@ namespace paludis
                     return _empty_masks.end();
             }
 
+            /**
+             * Iterator over the user package unmasks.
+             */
             typedef IndirectIterator<std::vector<PackageDepAtom::ConstPointer>::const_iterator,
                     const PackageDepAtom> UserUnmasksIterator;
 
+            /**
+             * Iterator to the start of the user package unmasks.
+             */
             UserUnmasksIterator begin_user_unmasks(const QualifiedPackageName & d) const
             {
                 std::map<QualifiedPackageName, std::vector<PackageDepAtom::ConstPointer> >::const_iterator r;
@@ -181,6 +229,9 @@ namespace paludis
                     return _empty_masks.begin();
             }
 
+            /**
+             * Iterator to past the end of the user package unmasks.
+             */
             UserUnmasksIterator end_user_unmasks(const QualifiedPackageName & d) const
             {
                 std::map<QualifiedPackageName, std::vector<PackageDepAtom::ConstPointer> >::const_iterator r;
@@ -190,8 +241,15 @@ namespace paludis
                     return _empty_masks.end();
             }
 
+            /**
+             * Iterator to the start of the use configuration.
+             */
             typedef std::vector<UseConfigEntry>::const_iterator UseConfigIterator;
 
+            /**
+             * Iterator to the start of the use configuration for a particular
+             * package.
+             */
             UseConfigIterator begin_use_config(const QualifiedPackageName & q) const
             {
                 std::map<QualifiedPackageName, std::vector<UseConfigEntry> >::const_iterator r;
@@ -201,6 +259,10 @@ namespace paludis
                     return _empty_use.begin();
             }
 
+            /**
+             * Iterator to past the end of the use configuration for a
+             * particular package.
+             */
             UseConfigIterator end_use_config(const QualifiedPackageName & q) const
             {
                 std::map<QualifiedPackageName, std::vector<UseConfigEntry> >::const_iterator r;
@@ -210,13 +272,22 @@ namespace paludis
                     return _empty_use.end();
             }
 
+            /**
+             * Iterator over the default use settings.
+             */
             typedef std::vector<std::pair<UseFlagName, UseFlagState> >::const_iterator DefaultUseIterator;
 
+            /**
+             * Iterator to the start of the default use settings.
+             */
             DefaultUseIterator begin_default_use() const
             {
                 return _default_use.begin();
             }
 
+            /**
+             * Iterator to past the end of the default use settings.
+             */
             DefaultUseIterator end_default_use() const
             {
                 return _default_use.end();
diff --git a/paludis/dep_list.cc b/paludis/dep_list.cc
index 06108b673..31b4be655 100644
--- a/paludis/dep_list.cc
+++ b/paludis/dep_list.cc
@@ -150,6 +150,7 @@ DepList::visit(const AllDepAtom * const v)
         (*i)->accept(this);
 }
 
+#ifndef DOXYGEN
 struct DepListEntryMatcher :
     public std::unary_function<bool, const DepListEntry &>
 {
@@ -174,6 +175,7 @@ struct DepListEntryMatcher :
         return true;
     }
 };
+#endif
 
 void
 DepList::visit(const PackageDepAtom * const p)
diff --git a/paludis/filter_insert_iterator.hh b/paludis/filter_insert_iterator.hh
index 79324ea8c..22d0ac32b 100644
--- a/paludis/filter_insert_iterator.hh
+++ b/paludis/filter_insert_iterator.hh
@@ -26,6 +26,13 @@
 
 namespace paludis
 {
+    /**
+     * A FilterInsertIterator is an insert iterator that only performs an insert
+     * if a particular predicate function returns true for the object to be
+     * inserted.
+     *
+     * \ingroup Iterator
+     */
     template <typename Iter_, typename Pred_>
     class FilterInsertIterator :
         public std::iterator<typename std::iterator_traits<Iter_>::iterator_category, void, void, void, void>
@@ -101,6 +108,8 @@ namespace paludis
 
     /**
      * Convenience function: make a FilterInsertIterator.
+     *
+     * \ingroup Iterator
      */
     template <typename Iter_, typename Pred_>
     FilterInsertIterator<Iter_, Pred_> filter_inserter(
diff --git a/paludis/getenv_TEST.cc b/paludis/getenv_TEST.cc
index 46a5557bb..fc9c03403 100644
--- a/paludis/getenv_TEST.cc
+++ b/paludis/getenv_TEST.cc
@@ -27,6 +27,12 @@ using namespace paludis;
 
 namespace test_cases
 {
+
+    /**
+     * \test Test getenv_with_default.
+     *
+     * \ingroup Test
+     */
     struct GetenvWithDefaultTest : TestCase
     {
         GetenvWithDefaultTest() : TestCase("getenv_with_default") { }
@@ -39,6 +45,11 @@ namespace test_cases
         }
     } test_getenv_with_default;
 
+    /**
+     * \test Test getenv_or_error.
+     *
+     * \ingroup Test
+     */
     struct GetenvOrErrorTest : TestCase
     {
         GetenvOrErrorTest() : TestCase("getenv_or_error") { }
diff --git a/paludis/indirect_iterator.hh b/paludis/indirect_iterator.hh
index a73b8cbe3..cfe553af7 100644
--- a/paludis/indirect_iterator.hh
+++ b/paludis/indirect_iterator.hh
@@ -64,6 +64,8 @@ namespace paludis
     /**
      * An IndirectIterator is an iterator adapter that does one additional level
      * of dereferencing.
+     *
+     * \ingroup Iterator
      */
     template <typename Iter_, typename Value_>
     class IndirectIterator : public std::iterator<typename std::iterator_traits<Iter_>::iterator_category, Value_>,
diff --git a/paludis/is_file_with_extension_TEST.cc b/paludis/is_file_with_extension_TEST.cc
index 55f03361a..bee8559fb 100644
--- a/paludis/is_file_with_extension_TEST.cc
+++ b/paludis/is_file_with_extension_TEST.cc
@@ -29,6 +29,11 @@ using namespace test;
 
 namespace test_cases
 {
+    /**
+     * \test Test IsFileWithExtension.
+     *
+     * \ingroup Test
+     */
     struct IsFileWithExtensionTest : TestCase
     {
         IsFileWithExtensionTest() : TestCase("is file with extension") { }
@@ -51,6 +56,11 @@ namespace test_cases
         }
     } test_is_file_with_extension;
 
+    /**
+     * \test Test IsFileWithExtension with a prefix.
+     *
+     * \ingroup Test
+     */
     struct IsFileWithExtensionPrefixTest : TestCase
     {
         IsFileWithExtensionPrefixTest() : TestCase("is file with extension (with prefix)") { }
diff --git a/paludis/key_value_config_file_TEST.cc b/paludis/key_value_config_file_TEST.cc
index eb076b0d1..419d9135d 100644
--- a/paludis/key_value_config_file_TEST.cc
+++ b/paludis/key_value_config_file_TEST.cc
@@ -32,6 +32,11 @@ using namespace test;
 
 namespace test_cases
 {
+    /**
+     * \test Test KeyValueConfigFile basics.
+     *
+     * \ingroup Test
+     */
     struct KeyValueConfigFileTest : TestCase
     {
         KeyValueConfigFileTest() : TestCase("key value config file") { }
@@ -55,6 +60,11 @@ namespace test_cases
         }
     } test_key_value_config_file;
 
+    /**
+     * \test Test KeyValueConfigFile variables.
+     *
+     * \ingroup Test
+     */
     struct KeyValueConfigFileVarsTest : TestCase
     {
         KeyValueConfigFileVarsTest() : TestCase("key value config file with vars") { }
@@ -73,6 +83,11 @@ namespace test_cases
         }
     } test_key_value_config_file_vars;
 
+    /**
+     * \test Test KeyValueConfigFile errors.
+     *
+     * \ingroup Test
+     */
     struct KeyValueConfigFileErrorsTest : TestCase
     {
         KeyValueConfigFileErrorsTest() : TestCase("key value config file with errors") { }
diff --git a/paludis/translate_insert_iterator.hh b/paludis/translate_insert_iterator.hh
index d8755ba4b..b0afa7b42 100644
--- a/paludis/translate_insert_iterator.hh
+++ b/paludis/translate_insert_iterator.hh
@@ -26,6 +26,12 @@
 
 namespace paludis
 {
+    /**
+     * A TranslateInsertIterator is an insert iterator that calls some function
+     * upon an item before inserting it.
+     *
+     * \ingroup Iterator
+     */
     template <typename Iter_, typename Trans_>
     class TranslateInsertIterator :
         public std::iterator<typename std::iterator_traits<Iter_>::iterator_category, void, void, void, void>
@@ -35,6 +41,10 @@ namespace paludis
             Trans_ _t;
 
         public:
+            /**
+             * Fake a container_type entry to allow a TranslateInsertIterator to
+             * work with other iterator adapters.
+             */
             struct container_type
             {
                 typedef typename Trans_::argument_type value_type;
@@ -104,6 +114,8 @@ namespace paludis
 
     /**
      * Convenience function: make a TranslateInsertIterator.
+     *
+     * \ingroup Iterator
      */
     template <typename Iter_, typename Trans_>
     TranslateInsertIterator<Iter_, Trans_> translate_inserter(