aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-09 07:38:42 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-09 07:38:42 +0000
commiteb70ca8daed36a1513dc6da3c97c7e2620412fd4 (patch)
treedbdf81e75415dd61698c86ca97afb573d1bdcd9b
parent57d6b8941a42e726a6e5caadfea0a775ab841571 (diff)
downloadpaludis-eb70ca8daed36a1513dc6da3c97c7e2620412fd4.tar.gz
paludis-eb70ca8daed36a1513dc6da3c97c7e2620412fd4.tar.xz
More doxygen work
-rw-r--r--doc/doc_main.doxygen32
-rw-r--r--doc/examples/Makefile.am34
-rw-r--r--doc/examples/example_name.cc107
-rw-r--r--doc/examples/example_package_database.cc105
-rw-r--r--doc/examples/example_version_operator.cc116
-rw-r--r--doc/examples/example_version_spec.cc99
-rw-r--r--paludis/name-fwd.hh45
-rw-r--r--paludis/name.cc6
-rw-r--r--paludis/name.hh78
-rw-r--r--paludis/name.se4
-rw-r--r--paludis/name.sr4
-rw-r--r--paludis/package_database-fwd.hh6
-rw-r--r--paludis/package_database.cc26
-rw-r--r--paludis/package_database.hh81
-rw-r--r--paludis/package_database.se2
-rw-r--r--paludis/repository_info-fwd.hh6
-rw-r--r--paludis/repository_info.cc10
-rw-r--r--paludis/repository_info.hh14
-rw-r--r--paludis/version_operator-fwd.hh8
-rw-r--r--paludis/version_operator.cc6
-rw-r--r--paludis/version_operator.hh20
-rw-r--r--paludis/version_operator.se2
-rw-r--r--paludis/version_requirements-fwd.hh14
-rw-r--r--paludis/version_requirements.hh10
-rw-r--r--paludis/version_requirements.sr3
-rw-r--r--paludis/version_spec-fwd.hh6
-rw-r--r--paludis/version_spec.cc19
-rw-r--r--paludis/version_spec.hh20
-rw-r--r--paludis/version_spec.sr2
29 files changed, 700 insertions, 185 deletions
diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index 861933e..845a09b 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -149,7 +149,7 @@ using namespace paludis;
/** \defgroup g_query "Query"
*
- * \ingroup g_paludis
+ * \ingroup g_package_database
*
* Queries are used by PackageDatabase::query. They provide a flexible, mergeable,
* efficient way of specifying which IDs should be returned in the result.
@@ -161,3 +161,33 @@ using namespace paludis;
* - \ref example_match_package.cc "example_match_package.cc"
*/
+/** \defgroup g_package_database "Package Database"
+ *
+ * \ingroup g_paludis
+ *
+ * A PackageDatabase, which is owned by an Environment, contains a number of
+ * Repository instances and supports various querying methods.
+ *
+ * \section Examples
+ *
+ * - \ref example_package_database.cc "example_package_database.cc"
+ * - \ref example_query.cc "example_query.cc"
+ * - \ref example_query_delegate.cc "example_query_delegate.cc"
+ */
+
+/** \defgroup g_names "Names and Versions"
+ *
+ * \ingroup g_names
+ *
+ * Paludis uses 'smart' classes for holding names and versions, allowing for
+ * substantially more static checking and much more convenient and useful
+ * runtime checking of data.
+ *
+ * \section Examples
+ *
+ * - \ref example_name.cc "example_name.cc"
+ * - \ref example_version_spec.cc "example_version_spec.cc"
+ * - \ref example_version_operator.cc "example_version_operator.cc"
+ */
+
+
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index ae9abff..8844762 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -27,7 +27,11 @@ noinst_PROGRAMS = \
example_repository \
example_match_package \
example_query \
- example_query_delegate
+ example_query_delegate \
+ example_package_database \
+ example_version_operator \
+ example_version_spec \
+ example_name
EXTRA_DIST = $(noinst_SCRIPTS)
@@ -134,14 +138,38 @@ example_match_package_LDFLAGS = \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/args/libpaludisargs.la
+example_query_delegate_SOURCES = example_query_delegate.cc
+example_query_delegate_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
example_query_SOURCES = example_query.cc
example_query_LDFLAGS = \
libpaludisexamples.a \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/args/libpaludisargs.la
-example_query_delegate_SOURCES = example_query_delegate.cc
-example_query_delegate_LDFLAGS = \
+example_package_database_SOURCES = example_package_database.cc
+example_package_database_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_version_operator_SOURCES = example_version_operator.cc
+example_version_operator_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_version_spec_SOURCES = example_version_spec.cc
+example_version_spec_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
+example_name_SOURCES = example_name.cc
+example_name_LDFLAGS = \
libpaludisexamples.a \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/args/libpaludisargs.la
diff --git a/doc/examples/example_name.cc b/doc/examples/example_name.cc
new file mode 100644
index 0000000..a56a177
--- /dev/null
+++ b/doc/examples/example_name.cc
@@ -0,0 +1,107 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_name.cc "example_name.cc" .
+ *
+ * \ingroup g_names
+ */
+
+/** \example example_name.cc
+ *
+ * This example demonstrates how to use name classes.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <cstdlib>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::setw;
+using std::left;
+
+namespace
+{
+ /* Try to create a name and show some information about it */
+ template <typename NameType_>
+ void show_name(const std::string & type_string, const std::string & value)
+ {
+ cout << type_string << " " << value << ":" << endl;
+ try
+ {
+ /* Names can be explicitly created from a string. If an invalid
+ * value is given, an exception is thrown. */
+ NameType_ name(value);
+
+ /* Names can be written to a stream. */
+ cout << " " << left << setw(24) << "To stream:" << " " << name << endl;
+
+ /* Names can be stringified if a raw string is needed. */
+ cout << " " << left << setw(24) << "stringify(n).length:"
+ << " " << stringify(name).length() << endl;
+ }
+ catch (const NameError & e)
+ {
+ cout << " " << left << setw(24) << "Exception:" << " '" <<
+ e.message() << "' (" << e.what() << ")" << endl;
+ }
+ cout << endl;
+ }
+}
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_name", "EXAMPLE_NAME_OPTIONS", "EXAMPLE_NAME_CMDLINE");
+
+ /* Most names are simply validated string classes. There is no implicit
+ * conversion to or from strings to increase static checking. The
+ * IUseFlag and QualifiedPackageName names are special -- they are
+ * composites, rather than simply validated strings. */
+ show_name<SetName>("SetName", "world");
+ show_name<SetName>("SetName", "not*valid");
+ show_name<PackageNamePart>("PackageNamePart", "fred");
+ show_name<PackageNamePart>("PackageNamePart", "not/valid");
+ show_name<QualifiedPackageName>("QualifiedPackageName", "cat/pkg");
+ show_name<QualifiedPackageName>("QualifiedPackageName", "not-valid");
+
+ QualifiedPackageName q1("cat/pkg"), q2(CategoryNamePart("cat") + PackageNamePart("pkg"));
+ cout << q1 << " " << (q1 == q2 ? "==" : "!=") << " " << q2 << endl;
+ cout << q1 << " has category '" << q1.category << "' and package part '" << q1.package << "'" << endl;
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return EXIT_SUCCESS;
+}
+
diff --git a/doc/examples/example_package_database.cc b/doc/examples/example_package_database.cc
new file mode 100644
index 0000000..6adb7a6
--- /dev/null
+++ b/doc/examples/example_package_database.cc
@@ -0,0 +1,105 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_package_database.cc "example_package_database.cc" .
+ *
+ * \ingroup g_package_database
+ */
+
+/** \example example_package_database.cc
+ *
+ * This example demonstrates how to use PackageDatabase.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <algorithm>
+#include <cstdlib>
+#include <set>
+#include <map>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::setw;
+using std::left;
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_dep_spec_flattener", "EXAMPLE_DEP_SPEC_FLATTENER_OPTIONS", "EXAMPLE_DEP_SPEC_FLATTENER_CMDLINE");
+
+ /* We start with an Environment, respecting the user's '--environment' choice. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* The most useful PackageDatabase method is PackageDatabase::query,
+ * which is covered in other examples. But there are others: */
+ if (env->package_database()->has_repository_named(RepositoryName("gentoo")))
+ {
+ tr1::shared_ptr<const Repository> repo(env->package_database()->fetch_repository(RepositoryName("gentoo")));
+ cout << "Repository 'gentoo' exists, and has format '" << repo->format() << "'" << endl;
+ }
+
+ /* Our favourite repository is the least important non-special (e.g.
+ * virtual) installable repository. Some clients use this as a hint to
+ * not display a ::repository suffix for things from this repository. */
+ cout << "Our favourite repository is '" << env->package_database()->favourite_repository() << "'" << endl;
+
+ /* Users often expect to be able to refer to a package by its name part
+ * only (e.g. 'foo' rather than 'app-misc/foo'). This has to be
+ * disambiguated as follows: */
+ try
+ {
+ QualifiedPackageName name(env->package_database()->fetch_unique_qualified_package_name(
+ PackageNamePart("git")));
+ cout << "The only package named 'git' is '" << name << "'" << endl;
+ }
+ catch (const NoSuchPackageError & e)
+ {
+ cout << "There is no package named 'git'" << endl;
+ }
+ catch (const AmbiguousPackageNameError & e)
+ {
+ cout << "There are several packages named 'git':" << endl;
+ for (AmbiguousPackageNameError::OptionsConstIterator o(e.begin_options()), o_end(e.end_options()) ;
+ o != o_end ; ++o)
+ cout << " " << *o << endl;
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return EXIT_SUCCESS;
+}
+
+
diff --git a/doc/examples/example_version_operator.cc b/doc/examples/example_version_operator.cc
new file mode 100644
index 0000000..1bea6e2
--- /dev/null
+++ b/doc/examples/example_version_operator.cc
@@ -0,0 +1,116 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_version_operator.cc "example_version_operator.cc" .
+ *
+ * \ingroup g_names
+ */
+
+/** \example example_version_operator.cc
+ *
+ * This example demonstrates how to use VersionOperator.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <cstdlib>
+#include <set>
+#include <list>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::setw;
+using std::left;
+using std::boolalpha;
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_version_operator", "EXAMPLE_VERSION_OPERATOR_OPTIONS", "EXAMPLE_VERSION_OPERATOR_CMDLINE");
+
+ /* Make a set of versions */
+ std::set<VersionSpec> versions;
+ versions.insert(VersionSpec("1.0"));
+ versions.insert(VersionSpec("1.1"));
+ versions.insert(VersionSpec("1.2"));
+ versions.insert(VersionSpec("1.2-r1"));
+ versions.insert(VersionSpec("2.0"));
+
+ /* And a list of operators */
+ std::list<VersionOperator> operators;
+ operators.push_back(VersionOperator("="));
+ operators.push_back(VersionOperator(">="));
+ operators.push_back(VersionOperator("~"));
+ operators.push_back(VersionOperator("<"));
+ operators.push_back(VersionOperator("~>"));
+
+ /* Display a header */
+ cout << " " << left << setw(8) << "LHS" << " | " << left << setw(8) << "RHS";
+ for (std::list<VersionOperator>::const_iterator o(operators.begin()), o_end(operators.end()) ;
+ o != o_end ; ++o)
+ cout << " | " << setw(8) << *o;
+ cout << endl << std::string(10, '-');
+ for (unsigned x(0) ; x <= operators.size() ; ++x)
+ cout << "+" << std::string(10, '-');
+ cout << endl;
+
+ /* For each pair of versions... */
+ for (std::set<VersionSpec>::const_iterator v1(versions.begin()), v1_end(versions.end()) ;
+ v1 != v1_end ; ++v1)
+ {
+ for (std::set<VersionSpec>::const_iterator v2(versions.begin()), v2_end(versions.end()) ;
+ v2 != v2_end ; ++v2)
+ {
+ cout << " " << left << setw(8) << *v1 << " | " << left << setw(8) << *v2;
+
+ /* Apply all of our operators, and show the results */
+ for (std::list<VersionOperator>::const_iterator o(operators.begin()), o_end(operators.end()) ;
+ o != o_end ; ++o)
+ {
+ /* VersionOperator::as_version_spec_comparator returns a
+ * binary boolean functor. */
+ cout << " | " << left << setw(8) << boolalpha << (o->as_version_spec_comparator()(*v1, *v2));
+ }
+
+ cout << endl;
+ }
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return EXIT_SUCCESS;
+}
+
+
+
diff --git a/doc/examples/example_version_spec.cc b/doc/examples/example_version_spec.cc
new file mode 100644
index 0000000..186fd79
--- /dev/null
+++ b/doc/examples/example_version_spec.cc
@@ -0,0 +1,99 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_version_spec.cc "example_version_spec.cc" .
+ *
+ * \ingroup g_names
+ */
+
+/** \example example_version_spec.cc
+ *
+ * This example demonstrates how to use VersionSpec.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+#include <cstdlib>
+#include <set>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::setw;
+using std::left;
+using std::boolalpha;
+using std::hex;
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_version_spec", "EXAMPLE_VERSION_SPEC_OPTIONS", "EXAMPLE_VERSION_SPEC_CMDLINE");
+
+ /* Make a set of versions */
+ std::set<VersionSpec> versions;
+ versions.insert(VersionSpec("1.0"));
+ versions.insert(VersionSpec("1.1"));
+ versions.insert(VersionSpec("1.2"));
+ versions.insert(VersionSpec("1.2-r1"));
+ versions.insert(VersionSpec("2.0"));
+ versions.insert(VersionSpec("2.0-try1"));
+ versions.insert(VersionSpec("2.0-scm"));
+ versions.insert(VersionSpec("9999"));
+
+ /* For each version... */
+ for (std::set<VersionSpec>::const_iterator v(versions.begin()), v_end(versions.end()) ;
+ v != v_end ; ++v)
+ {
+ /* Versions are stringifiable */
+ cout << *v << ":" << endl;
+
+ /* Show the output of various members. Not all of these are of much
+ * direct use. */
+ cout << " " << left << setw(24) << "Hash value:" << " " << "0x" << hex << v->hash_value() << endl;
+ cout << " " << left << setw(24) << "Remove revision:" << " " << v->remove_revision() << endl;
+ cout << " " << left << setw(24) << "Revision only:" << " " << v->revision_only() << endl;
+ cout << " " << left << setw(24) << "Bump:" << " " << v->bump() << endl;
+ cout << " " << left << setw(24) << "Is scm?" << " " << boolalpha << v->is_scm() << endl;
+ cout << " " << left << setw(24) << "Has -try?" << " " << boolalpha << v->has_try_part() << endl;
+ cout << " " << left << setw(24) << "Has -scm?" << " " << boolalpha << v->has_scm_part() << endl;
+ cout << endl;
+ }
+ }
+ catch (const Exception & e)
+ {
+ /* Paludis exceptions can provide a handy human-readable backtrace and
+ * an explanation message. Where possible, these should be displayed. */
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.backtrace("\n * ")
+ << e.message() << " (" << e.what() << ")" << endl;
+ return EXIT_FAILURE;
+ }
+ catch (const std::exception & e)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * " << e.what() << endl;
+ return EXIT_FAILURE;
+ }
+ catch (...)
+ {
+ cout << endl;
+ cout << "Unhandled exception:" << endl
+ << " * Unknown exception type. Ouch..." << endl;
+ return EXIT_FAILURE;
+ }
+
+ return EXIT_SUCCESS;
+}
+
+
+
+
diff --git a/paludis/name-fwd.hh b/paludis/name-fwd.hh
index 2eed76e..73a61f1 100644
--- a/paludis/name-fwd.hh
+++ b/paludis/name-fwd.hh
@@ -26,6 +26,12 @@
#include <paludis/util/attributes.hh>
#include <string>
+/** \file
+ * Forward declarations for paludis/name.hh .
+ *
+ * \ingroup g_names
+ */
+
namespace paludis
{
class PackageNamePartError;
@@ -35,14 +41,14 @@ namespace paludis
* A PackageNamePart holds a std::string that is a valid name for the
* package part of a QualifiedPackageName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, PackageNamePartValidator> PackageNamePart;
/**
* Holds a set of PackageNamePart instances.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<PackageNamePart> PackageNamePartSet;
@@ -53,14 +59,14 @@ namespace paludis
* A CategoryNamePart holds a std::string that is a valid name for the
* category part of a QualifiedPackageName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, CategoryNamePartValidator> CategoryNamePart;
/**
* Holds a set of CategoryNamePart instances.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<CategoryNamePart> CategoryNamePartSet;
@@ -71,14 +77,14 @@ namespace paludis
/**
* A UseFlagName holds a std::string that is a valid name for a USE flag.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, UseFlagNameValidator> UseFlagName;
/**
* A collection of UseFlagName instances.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<UseFlagName> UseFlagNameSet;
@@ -90,26 +96,31 @@ namespace paludis
/**
* Output a QualifiedPackageName to a stream.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
std::ostream & operator<< (std::ostream &, const QualifiedPackageName &) PALUDIS_VISIBLE;
/**
* Output an IUseFlag to a stream.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
std::ostream & operator<< (std::ostream &, const IUseFlag &) PALUDIS_VISIBLE;
/**
* Holds a collection of QualifiedPackageName instances.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<QualifiedPackageName> QualifiedPackageNameSet;
class QualifiedPackageNameError;
+ /**
+ * A CategoryNamePart plus a PackageNamePart is a QualifiedPackageName.
+ *
+ * \ingroup g_names
+ */
inline const QualifiedPackageName
operator+ (const CategoryNamePart & c, const PackageNamePart & p) PALUDIS_ATTRIBUTE((warn_unused_result));
@@ -119,7 +130,7 @@ namespace paludis
/**
* A SlotName holds a std::string that is a valid name for a SLOT.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, SlotNameValidator> SlotName;
@@ -130,14 +141,14 @@ namespace paludis
* A RepositoryName holds a std::string that is a valid name for a
* Repository.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, RepositoryNameValidator, false> RepositoryName;
/**
* Holds a collection of RepositoryName instances.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Sequence<RepositoryName> RepositoryNameSequence;
@@ -149,14 +160,14 @@ namespace paludis
/**
* A KeywordName holds a std::string that is a valid name for a KEYWORD.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, KeywordNameValidator> KeywordName;
/**
* Holds a collection of KeywordName instances.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<KeywordName> KeywordNameSet;
@@ -166,21 +177,21 @@ namespace paludis
/**
* A SetName holds a std::string that is a valid name for a set.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Validated<std::string, SetNameValidator> SetName;
/**
* A collection of set names.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<SetName> SetNameSet;
/**
* A collection of use flags.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
typedef Set<IUseFlag> IUseFlagSet;
}
diff --git a/paludis/name.cc b/paludis/name.cc
index e472198..de9daec 100644
--- a/paludis/name.cc
+++ b/paludis/name.cc
@@ -26,12 +26,6 @@
#include <ostream>
#include <utility>
-/** \file
- * Implementation of name.hh things.
- *
- * \ingroup grpnames
- */
-
using namespace paludis;
#include <paludis/name-sr.cc>
diff --git a/paludis/name.hh b/paludis/name.hh
index 8232a2b..af5c211 100644
--- a/paludis/name.hh
+++ b/paludis/name.hh
@@ -30,9 +30,13 @@
#include <iosfwd>
/** \file
- * Declarations for various Name classes.
+ * Declarations for Name classes.
*
- * \ingroup grpnames
+ * \ingroup g_names
+ *
+ * \section Examples
+ *
+ * - \ref example_name.cc "example_name.cc"
*/
namespace paludis
@@ -41,10 +45,11 @@ namespace paludis
* A PackageNamePartError is thrown if an invalid value is assigned to
* a PackageNamePart.
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
- class PALUDIS_VISIBLE PackageNamePartError : public NameError
+ class PALUDIS_VISIBLE PackageNamePartError :
+ public NameError
{
public:
/**
@@ -57,7 +62,7 @@ namespace paludis
* A PackageNamePartValidator handles validation rules for the value
* of a PackageNamePart.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE PackageNamePartValidator :
private InstantiationPolicy<PackageNamePartValidator, instantiation_method::NonInstantiableTag>
@@ -73,10 +78,11 @@ namespace paludis
* A CategoryNamePartError is thrown if an invalid value is assigned to
* a CategoryNamePart.
*
- * \ingroup grpexceptions
- * \ingroup grpnames
+ * \ingroup g_exceptions
+ * \ingroup g_names
*/
- class PALUDIS_VISIBLE CategoryNamePartError : public NameError
+ class PALUDIS_VISIBLE CategoryNamePartError :
+ public NameError
{
public:
/**
@@ -89,7 +95,7 @@ namespace paludis
* A CategoryNamePartValidator handles validation rules for the value
* of a CategoryNamePart.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE CategoryNamePartValidator :
private InstantiationPolicy<CategoryNamePartValidator, instantiation_method::NonInstantiableTag>
@@ -105,10 +111,11 @@ namespace paludis
* A UseFlagNameError is thrown if an invalid value is assigned to
* a UseFlagName.
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
- class PALUDIS_VISIBLE UseFlagNameError : public NameError
+ class PALUDIS_VISIBLE UseFlagNameError :
+ public NameError
{
public:
/**
@@ -121,10 +128,11 @@ namespace paludis
* An IUseFlagNameError is thrown if an invalid value is assigned to
* an IUseFlagName.
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
- class PALUDIS_VISIBLE IUseFlagNameError : public NameError
+ class PALUDIS_VISIBLE IUseFlagNameError :
+ public NameError
{
public:
///\name Basic operations
@@ -141,7 +149,7 @@ namespace paludis
* A UseFlagNameValidator handles validation rules for the value of a
* UseFlagName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE UseFlagNameValidator :
private InstantiationPolicy<UseFlagNameValidator, instantiation_method::NonInstantiableTag>
@@ -160,8 +168,8 @@ namespace paludis
* assigned to a QualifiedPackageName (alternatively, the exception
* raised may be a PackageNamePartError or a CategoryNamePartError).
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
class PALUDIS_VISIBLE QualifiedPackageNameError : public NameError
{
@@ -172,12 +180,6 @@ namespace paludis
QualifiedPackageNameError(const std::string &) throw ();
};
- /**
- * Convenience operator to make a QualifiedPackageName from a
- * PackageNamePart and a CategoryNamePart.
- *
- * \ingroup grpnames
- */
inline const QualifiedPackageName
operator+ (const CategoryNamePart & c, const PackageNamePart & p)
{
@@ -188,8 +190,8 @@ namespace paludis
* A SlotNameError is thrown if an invalid value is assigned to
* a SlotName.
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
class PALUDIS_VISIBLE SlotNameError : public NameError
{
@@ -204,7 +206,7 @@ namespace paludis
* A SlotNameValidator handles validation rules for the value of a
* SlotName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE SlotNameValidator :
private InstantiationPolicy<SlotNameValidator, instantiation_method::NonInstantiableTag>
@@ -220,8 +222,8 @@ namespace paludis
* A RepositoryNameError is thrown if an invalid value is assigned to
* a RepositoryName.
*
- * \ingroup grpexceptions
- * \ingroup grpnames
+ * \ingroup g_exceptions
+ * \ingroup g_names
*/
class PALUDIS_VISIBLE RepositoryNameError : public NameError
{
@@ -236,7 +238,7 @@ namespace paludis
* A RepositoryNameValidator handles validation rules for the value
* of a RepositoryName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE RepositoryNameValidator :
private InstantiationPolicy<RepositoryNameValidator, instantiation_method::NonInstantiableTag>
@@ -251,7 +253,7 @@ namespace paludis
/**
* Arbitrary useless comparator for RepositoryName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE RepositoryNameComparator
{
@@ -268,7 +270,7 @@ namespace paludis
* A KeywordNameValidator handles validation rules for the value of a
* KeywordName.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
struct PALUDIS_VISIBLE KeywordNameValidator :
private InstantiationPolicy<KeywordNameValidator, instantiation_method::NonInstantiableTag>
@@ -284,8 +286,8 @@ namespace paludis
* A KeywordNameError is thrown if an invalid value is assigned to
* a KeywordName.
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
class PALUDIS_VISIBLE KeywordNameError : public NameError
{
@@ -300,7 +302,7 @@ namespace paludis
* A SetNameValidator handles validation rules for the value of a
* SetName.
*
- * \ingroup grpnames
+ * \ingroup g_exceptions
*/
struct PALUDIS_VISIBLE SetNameValidator :
private InstantiationPolicy<SetNameValidator, instantiation_method::NonInstantiableTag>
@@ -316,8 +318,8 @@ namespace paludis
* A SetNameError is thrown if an invalid value is assigned to
* a SetName.
*
- * \ingroup grpnames
- * \ingroup grpexceptions
+ * \ingroup g_exceptions
+ * \ingroup g_names
*/
class PALUDIS_VISIBLE SetNameError : public NameError
{
diff --git a/paludis/name.se b/paludis/name.se
index 1e66fd1..b9c6059 100644
--- a/paludis/name.se
+++ b/paludis/name.se
@@ -13,7 +13,7 @@ make_enum_UseFlagState()
/**
* A USE flag can be on, off or unspecified.
*
- * \ingroup grpnames
+ * \ingroup g_names
*/
END
}
@@ -33,7 +33,7 @@ make_enum_IUseFlagParseMode()
* How to parse an IUSE flag string.
*
* \see IUseFlag
- * \ingroup grpnames
+ * \ingroup g_names
*/
END
}
diff --git a/paludis/name.sr b/paludis/name.sr
index 29eca3e..617bac0 100644
--- a/paludis/name.sr
+++ b/paludis/name.sr
@@ -18,7 +18,7 @@ END
/**
* Represents a category plus package name.
*
- * \ingroup grpnames
+ * \ingroup g_names
* \nosubgrouping
*/
END
@@ -42,7 +42,7 @@ END
/**
* Represents an IUse flag.
*
- * \ingroup grpnames
+ * \ingroup g_names
* \nosubgrouping
*/
END
diff --git a/paludis/package_database-fwd.hh b/paludis/package_database-fwd.hh
index d0745b3..5c52c9a 100644
--- a/paludis/package_database-fwd.hh
+++ b/paludis/package_database-fwd.hh
@@ -23,6 +23,12 @@
#include <iosfwd>
#include <paludis/util/attributes.hh>
+/** \file
+ * Forward declarations for paludis/package_database.hh .
+ *
+ * \ingroup g_package_database
+ */
+
namespace paludis
{
class PackageDatabaseError;
diff --git a/paludis/package_database.cc b/paludis/package_database.cc
index 36679b2..bbef21e 100644
--- a/paludis/package_database.cc
+++ b/paludis/package_database.cc
@@ -39,10 +39,6 @@
#include <map>
#include <set>
-/** \file
- * Implementation of PackageDatabase.
- */
-
using namespace paludis;
#include "package_database-se.cc"
@@ -98,17 +94,9 @@ NoSuchRepositoryError::name() const
return _name;
}
-/**
- * Name data for an AmbiguousPackageNameError.
- *
- * \ingroup grpexceptions
- */
struct AmbiguousPackageNameError::NameData
{
- /// Our query name
std::string name;
-
- /// Our match names
std::list<std::string> names;
};
@@ -157,25 +145,11 @@ AmbiguousPackageNameError::name() const
namespace paludis
{
- /**
- * Implementation data for a PackageDatabase.
- *
- * \ingroup grppackagedatabase
- */
template<>
struct Implementation<PackageDatabase>
{
- /**
- * Our Repository instances.
- */
std::list<tr1::shared_ptr<Repository> > repositories;
-
- /**
- * Repository importances.
- */
std::multimap<int, std::list<tr1::shared_ptr<Repository> >::iterator> repository_importances;
-
- /// Our environment.
const Environment * environment;
};
}
diff --git a/paludis/package_database.hh b/paludis/package_database.hh
index 4c8a927..b1b2908 100644
--- a/paludis/package_database.hh
+++ b/paludis/package_database.hh
@@ -38,9 +38,15 @@
#include <libwrapiter/libwrapiter_forward_iterator-fwd.hh>
/** \file
- * Declarations for the PackageDatabase class and related utilities.
+ * Declarations for PackageDatabase.
*
- * \ingroup grppackagedatabase
+ * \ingroup g_package_database
+ *
+ * \section Examples
+ *
+ * - \ref example_package_database.cc "example_package_database.cc"
+ * - \ref example_query.cc "example_query.cc"
+ * - \ref example_query_delegate.cc "example_query_delegate.cc"
*/
namespace paludis
@@ -49,10 +55,11 @@ namespace paludis
* A PackageDatabaseError is an error that occurs when performing some
* operation upon a PackageDatabase.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
*/
- class PALUDIS_VISIBLE PackageDatabaseError : public Exception
+ class PALUDIS_VISIBLE PackageDatabaseError :
+ public Exception
{
protected:
/**
@@ -65,10 +72,11 @@ namespace paludis
* A PackageDatabaseLookupError descendent is thrown if an error occurs
* when looking for something in a PackageDatabase.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
*/
- class PALUDIS_VISIBLE PackageDatabaseLookupError : public PackageDatabaseError
+ class PALUDIS_VISIBLE PackageDatabaseLookupError :
+ public PackageDatabaseError
{
protected:
/**
@@ -81,8 +89,8 @@ namespace paludis
* Thrown if a PackageDatabase query results in more than one matching
* Package.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
* \nosubgrouping
*/
class PALUDIS_VISIBLE AmbiguousPackageNameError :
@@ -129,10 +137,12 @@ namespace paludis
* Thrown if a Repository with the same name as an existing member is added
* to a PackageDatabase.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
+ * \nosubgrouping
*/
- class PALUDIS_VISIBLE DuplicateRepositoryError : public PackageDatabaseError
+ class PALUDIS_VISIBLE DuplicateRepositoryError :
+ public PackageDatabaseError
{
public:
/**
@@ -145,27 +155,27 @@ namespace paludis
* Thrown if there is no Package in a PackageDatabase with the given
* name.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
*/
- class PALUDIS_VISIBLE NoSuchPackageError : public PackageDatabaseLookupError
+ class PALUDIS_VISIBLE NoSuchPackageError :
+ public PackageDatabaseLookupError
{
private:
std::string _name;
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
NoSuchPackageError(const std::string & name) throw ();
- /**
- * Destructor.
- */
virtual ~NoSuchPackageError() throw ()
{
}
+ ///\}
+
/**
* Name of the package.
*/
@@ -179,8 +189,8 @@ namespace paludis
* Thrown if a PackageDatabase::query() with qo_require_exactly_one does not
* get exactly one result.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
*/
class PALUDIS_VISIBLE NonUniqueQueryResultError :
public PackageDatabaseLookupError
@@ -196,8 +206,8 @@ namespace paludis
* Thrown if there is no Repository in a RepositoryDatabase with the given
* name.
*
- * \ingroup grpexceptions
- * \ingroup grppackagedatabase
+ * \ingroup g_exceptions
+ * \ingroup g_package_database
*/
class PALUDIS_VISIBLE NoSuchRepositoryError : public PackageDatabaseLookupError
{
@@ -228,25 +238,25 @@ namespace paludis
};
/**
- * A PackageDatabase can be queried for Package instances.
+ * A PackageDatabase, which is owned by an Environment, contains a number of
+ * Repository instances and supports various querying methods.
*
- * \ingroup grppackagedatabase
+ * \ingroup g_package_database
*/
class PALUDIS_VISIBLE PackageDatabase :
private PrivateImplementationPattern<PackageDatabase>,
private InstantiationPolicy<PackageDatabase, instantiation_method::NonCopyableTag>
{
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
explicit PackageDatabase(const Environment * const);
- /**
- * Destructor.
- */
~PackageDatabase();
+ ///\}
+
/**
* Add a repository.
*
@@ -287,6 +297,9 @@ namespace paludis
/**
* Disambiguate a package name.
+ *
+ * \throw AmbiguousPackageNameError if there is no unambiguous
+ * disabmiguation.
*/
QualifiedPackageName fetch_unique_qualified_package_name(
const PackageNamePart &) const
diff --git a/paludis/package_database.se b/paludis/package_database.se
index 6ce1d87..8bd92df 100644
--- a/paludis/package_database.se
+++ b/paludis/package_database.se
@@ -17,7 +17,7 @@ make_enum_QueryOrder()
* How to order paludis::PackageDatabase::query() results.
*
* \see PackageDatabase
- * \ingroup grppackagedatabase
+ * \ingroup g_package_database
*/
END
}
diff --git a/paludis/repository_info-fwd.hh b/paludis/repository_info-fwd.hh
index 7b23fda..e9fac7b 100644
--- a/paludis/repository_info-fwd.hh
+++ b/paludis/repository_info-fwd.hh
@@ -20,6 +20,12 @@
#ifndef PALUDIS_GUARD_PALUDIS_REPOSITORY_INFO_FWD_HH
#define PALUDIS_GUARD_PALUDIS_REPOSITORY_INFO_FWD_HH 1
+/** \file
+ * Forward declarations for paludis/repository_info.hh .
+ *
+ * \ingroup g_package_database
+ */
+
namespace paludis
{
class RepositoryInfo;
diff --git a/paludis/repository_info.cc b/paludis/repository_info.cc
index ddf5b6d..1a1f61d 100644
--- a/paludis/repository_info.cc
+++ b/paludis/repository_info.cc
@@ -33,11 +33,6 @@ using namespace paludis;
namespace paludis
{
- /**
- * Implementation data for RepositoryInfoSection.
- *
- * \ingroup grprepository
- */
template<>
struct Implementation<RepositoryInfoSection>
{
@@ -45,11 +40,6 @@ namespace paludis
std::map<std::string, std::string> kvs;
};
- /**
- * Implementation data for RepositoryInfo.
- *
- * \ingroup grprepository
- */
template<>
struct Implementation<RepositoryInfo>
{
diff --git a/paludis/repository_info.hh b/paludis/repository_info.hh
index 2b6f7b7..4511918 100644
--- a/paludis/repository_info.hh
+++ b/paludis/repository_info.hh
@@ -22,13 +22,23 @@
#include <paludis/repository_info-fwd.hh>
+/** \file
+ * Declarations for RepositoryInfo classes.
+ *
+ * \ingroup g_repository
+ *
+ * \section Examples
+ *
+ * - \ref example_repository.cc "example_repository.cc"
+ */
+
namespace paludis
{
/**
* A section of information about a Repository.
*
* \see RepositoryInfo
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryInfoSection :
@@ -72,7 +82,7 @@ namespace paludis
/**
* Information about a Repository, for the end user.
*
- * \ingroup grprepository
+ * \ingroup g_repository
* \nosubgrouping
*/
class PALUDIS_VISIBLE RepositoryInfo :
diff --git a/paludis/version_operator-fwd.hh b/paludis/version_operator-fwd.hh
index 8c735b4..f47a06b 100644
--- a/paludis/version_operator-fwd.hh
+++ b/paludis/version_operator-fwd.hh
@@ -23,6 +23,12 @@
#include <iosfwd>
#include <paludis/util/attributes.hh>
+/** \file
+ * Forward declarations for paludis/version_operator.hh .
+ *
+ * \ingroup g_names
+ */
+
namespace paludis
{
#include <paludis/version_operator-se.hh>
@@ -33,7 +39,7 @@ namespace paludis
/**
* A VersionOperator can be written to an ostream.
*
- * \ingroup grpversions
+ * \ingroup g_names
*/
std::ostream & operator<< (std::ostream & s, const VersionOperator &) PALUDIS_VISIBLE;
}
diff --git a/paludis/version_operator.cc b/paludis/version_operator.cc
index 8e0a7d2..c6c1e1f 100644
--- a/paludis/version_operator.cc
+++ b/paludis/version_operator.cc
@@ -22,12 +22,6 @@
#include <paludis/version_operator.hh>
#include <paludis/version_spec.hh>
-/** \file
- * Implementation for VersionOperator.
- *
- * \ingroup grpversions
- */
-
using namespace paludis;
#include <paludis/version_operator-se.cc>
diff --git a/paludis/version_operator.hh b/paludis/version_operator.hh
index 9a779a4..de00475 100644
--- a/paludis/version_operator.hh
+++ b/paludis/version_operator.hh
@@ -28,9 +28,14 @@
#include <string>
/** \file
- * Declarations for the VersionOperator class.
+ * Declarations for VersionOperator classes.
*
- * \ingroup grpversions
+ * \ingroup g_names
+ *
+ * \section Examples
+ *
+ * - \ref example_version_operator.cc "example_version_operator.cc"
+ * - \ref example_version_spec.cc "example_version_spec.cc"
*/
namespace paludis
@@ -38,7 +43,7 @@ namespace paludis
/**
* An operator attached to a VersionSpec, validated.
*
- * \ingroup grpversions
+ * \ingroup g_names
*/
class PALUDIS_VISIBLE VersionOperator :
public equality_operators::HasEqualityOperators
@@ -51,6 +56,9 @@ namespace paludis
VersionOperatorValue _v;
public:
+ ///\name Basic operations
+ ///\{
+
/**
* Constructor.
*/
@@ -84,6 +92,8 @@ namespace paludis
return *this;
}
+ ///\}
+
/**
* Return value.
*/
@@ -116,8 +126,8 @@ namespace paludis
/**
* Thrown if a bad version operator is encountered.
*
- * \ingroup grpversions
- * \ingroup grpexceptions
+ * \ingroup g_names
+ * \ingroup g_exceptions
*/
class PALUDIS_VISIBLE BadVersionOperatorError :
public Exception
diff --git a/paludis/version_operator.se b/paludis/version_operator.se
index a6e0137..78448db 100644
--- a/paludis/version_operator.se
+++ b/paludis/version_operator.se
@@ -18,7 +18,7 @@ make_enum_VersionOperatorValue()
/**
* Represents an operator attached to a VersionSpec.
*
- * \ingroup grpversions
+ * \ingroup g_names
*/
END
}
diff --git a/paludis/version_requirements-fwd.hh b/paludis/version_requirements-fwd.hh
index 7f46681..609ae28 100644
--- a/paludis/version_requirements-fwd.hh
+++ b/paludis/version_requirements-fwd.hh
@@ -26,6 +26,12 @@
#include <paludis/version_spec-fwd.hh>
#include <iosfwd>
+/** \file
+ * Forward declarations for paludis/version_requirements.hh .
+ *
+ * \ingroup g_dep_spec
+ */
+
namespace paludis
{
class VersionRequirement;
@@ -35,7 +41,7 @@ namespace paludis
* PackageDepSpec.
*
* \see PackageDepSpec
- * \ingroup grpversions
+ * \ingroup g_dep_spec
*/
typedef Sequence<VersionRequirement> VersionRequirements;
@@ -44,7 +50,7 @@ namespace paludis
* single entry.
*
* \see VersionRequirements
- * \ingroup grpversions
+ * \ingroup g_dep_spec
*/
tr1::shared_ptr<VersionRequirements> make_equal_to_version_requirements(const VersionSpec &) PALUDIS_VISIBLE;
@@ -52,7 +58,7 @@ namespace paludis
* Whether our version requirements are an 'and' or an 'or' set.
*
* \see PackageDepSpec
- * \ingroup grpversions
+ * \ingroup g_dep_spec
*/
enum VersionRequirementsMode
{
@@ -64,7 +70,7 @@ namespace paludis
/**
* Write a VersionRequirementsMode to a stream.
*
- * \ingroup grpversions
+ * \ingroup g_dep_spec
*/
std::ostream &
operator<< (std::ostream &, const VersionRequirementsMode &) PALUDIS_VISIBLE;
diff --git a/paludis/version_requirements.hh b/paludis/version_requirements.hh
index 412e3bf..571add0 100644
--- a/paludis/version_requirements.hh
+++ b/paludis/version_requirements.hh
@@ -25,6 +25,16 @@
#include <paludis/version_operator.hh>
#include <paludis/version_spec.hh>
+/** \file
+ * Declarations for version requirements classes.
+ *
+ * \ingroup g_dep_spec
+ *
+ * \section Examples
+ *
+ * - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
+ */
+
namespace paludis
{
#include <paludis/version_requirements-sr.hh>
diff --git a/paludis/version_requirements.sr b/paludis/version_requirements.sr
index 6632c6f..91a80a2 100644
--- a/paludis/version_requirements.sr
+++ b/paludis/version_requirements.sr
@@ -16,7 +16,8 @@ make_class_VersionRequirement()
* A requirement for a version, consisting of a VersionOperator and an associated
* VersionSpec.
*
- * \ingroup grpversions
+ * \ingroup g_dep_spec
+ * \see PackageDepSpec
* \see VersionSpec
* \see VersionOperator
* \see VersionRequirements
diff --git a/paludis/version_spec-fwd.hh b/paludis/version_spec-fwd.hh
index ca8d5ad..990e7fa 100644
--- a/paludis/version_spec-fwd.hh
+++ b/paludis/version_spec-fwd.hh
@@ -23,6 +23,12 @@
#include <iosfwd>
#include <paludis/util/attributes.hh>
+/** \file
+ * Forward declarations for paludis/version_spec.hh .
+ *
+ * \ingroup g_names
+ */
+
namespace paludis
{
class BadVersionSpecError;
diff --git a/paludis/version_spec.cc b/paludis/version_spec.cc
index 2ba7f4a..b097779 100644
--- a/paludis/version_spec.cc
+++ b/paludis/version_spec.cc
@@ -30,12 +30,6 @@
#include <vector>
#include <limits>
-/** \file
- * Implementation of VersionSpec.
- *
- * \ingroup grpversions
- */
-
using namespace paludis;
BadVersionSpecError::BadVersionSpecError(const std::string & name) throw () :
@@ -50,11 +44,6 @@ BadVersionSpecError::BadVersionSpecError(const std::string & name, const std::st
namespace
{
- /**
- * Type of a Part in a VersionSpec data vector.
- *
- * \ingroup grpversions
- */
enum PartKind
{
alpha,
@@ -77,24 +66,16 @@ namespace
namespace paludis
{
- /**
- * Implementation data for a VersionSpec.
- */
template<>
struct Implementation<VersionSpec>
{
- /// Our raw string representation.
std::string text;
-
- /// Our parts.
std::vector<Part> parts;
- /// Our hash
mutable Mutex hash_mutex;
mutable bool has_hash;
mutable std::size_t hash;
- /// Our is_scm
mutable Mutex is_scm_mutex;
mutable bool has_is_scm;
mutable bool is_scm;
diff --git a/paludis/version_spec.hh b/paludis/version_spec.hh
index 470e8c6..5e7e1a5 100644
--- a/paludis/version_spec.hh
+++ b/paludis/version_spec.hh
@@ -29,9 +29,14 @@
#include <string>
/** \file
- * Declarations of the VersionSpec class.
+ * Declarations for VersionSpec classes.
*
- * \ingroup grpversions
+ * \ingroup g_names
+ *
+ * \section Examples
+ *
+ * - \ref example_version_spec.cc "example_version_spec.cc"
+ * - \ref example_version_operator.cc "example_version_operator.cc"
*/
namespace paludis
@@ -39,8 +44,8 @@ namespace paludis
/**
* Thrown if a VersionSpec is created from an invalid version string.
*
- * \ingroup grpexceptions
- * \ingroup grpversions
+ * \ingroup g_exceptions
+ * \ingroup g_names
*/
class PALUDIS_VISIBLE BadVersionSpecError :
public NameError
@@ -58,7 +63,7 @@ namespace paludis
/**
* A VersionSpec represents a version number (for example, 1.2.3b-r1).
*
- * \ingroup grpversions
+ * \ingroup g_names
*/
class PALUDIS_VISIBLE VersionSpec :
private PrivateImplementationPattern<VersionSpec>,
@@ -67,6 +72,9 @@ namespace paludis
friend std::ostream & operator<< (std::ostream &, const VersionSpec &);
public:
+ ///\name Basic operations
+ ///\{
+
/**
* Constructor.
*/
@@ -87,6 +95,8 @@ namespace paludis
*/
const VersionSpec & operator= (const VersionSpec & other);
+ ///\}
+
///\name Comparison operators
///\{
diff --git a/paludis/version_spec.sr b/paludis/version_spec.sr
index 567db20..666c705 100644
--- a/paludis/version_spec.sr
+++ b/paludis/version_spec.sr
@@ -10,7 +10,7 @@ make_class_Part()
/**
* Internal use by VersionSpec.
*
- * \ingroup grpversions
+ * \ingroup g_names
* \nosubgrouping
*/
END