aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-05 20:07:06 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-05 20:07:06 +0000
commit5cbbc59d6c90e3ff9e69ccd28a6470a111c44205 (patch)
treefec9d1748fd814199925de1e8935c8d89ac37410
parentf354f4f17804a1b48b549646d5fdf0f9cf99ea9f (diff)
downloadpaludis-5cbbc59d6c90e3ff9e69ccd28a6470a111c44205.tar.gz
paludis-5cbbc59d6c90e3ff9e69ccd28a6470a111c44205.tar.xz
More doc work. Remove some legacy code.
-rw-r--r--doc/doc_main.doxygen17
-rw-r--r--doc/examples/Makefile.am16
-rw-r--r--doc/examples/example_dep_tag.cc198
-rw-r--r--doc/examples/example_environment.cc108
-rw-r--r--paludis/dep_label.hh1
-rw-r--r--paludis/dep_spec.hh1
-rw-r--r--paludis/dep_tag-fwd.hh8
-rw-r--r--paludis/dep_tag.cc26
-rw-r--r--paludis/dep_tag.hh43
-rw-r--r--paludis/dep_tag.sr2
-rw-r--r--paludis/dep_tree.hh1
-rw-r--r--paludis/distribution-fwd.hh6
-rw-r--r--paludis/distribution.hh25
-rw-r--r--paludis/distribution.sr2
-rw-r--r--paludis/environment-fwd.hh25
-rw-r--r--paludis/environment.cc2
-rw-r--r--paludis/environment.hh34
-rw-r--r--paludis/environment.se21
-rw-r--r--paludis/environment_implementation.hh18
-rw-r--r--paludis/files.m42
-rw-r--r--ruby/qa.cc2
21 files changed, 457 insertions, 101 deletions
diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index c68453f..001e120 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -1,5 +1,7 @@
/* vim: set ft=cpp tw=80 sw=4 et : */
+using namespace paludis;
+
/** \defgroup g_paludis Paludis
*
* Paludis public API.
@@ -52,10 +54,25 @@
*
* - \ref example_dep_label.cc "example_dep_label.cc"
* - \ref example_dep_spec.cc "example_dep_spec.cc"
+ * - \ref example_dep_tag.cc "example_dep_tag.cc"
* - \ref example_dep_tree.cc "example_dep_tree.cc"
* - \ref example_dep_spec_flattener.cc "example_dep_spec_flattener.cc"
*/
+/** \defgroup g_environment Environment
+ *
+ * \ingroup g_paludis
+ *
+ * An Environment subclass is the starting point for most programs. For programs
+ * that use user configuration, EnvironmentMaker is used to obtain an instance.
+ * For programs that operate without configuration, NoConfigEnvironment should
+ * be used instead.
+ *
+ * \section Examples
+ *
+ * - \ref example_environment.cc "example_environment.cc"
+ */
+
/** \defgroup g_exceptions Exceptions
*
* Exceptions and related utility classes.
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index 4006a64..f3bcea6 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -15,8 +15,10 @@ noinst_PROGRAMS = \
example_contents \
example_dep_label \
example_dep_spec \
+ example_dep_tag \
example_dep_tree \
- example_dep_spec_flattener
+ example_dep_spec_flattener \
+ example_environment
EXTRA_DIST = $(noinst_SCRIPTS)
@@ -63,12 +65,24 @@ example_dep_tree_LDFLAGS = \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/args/libpaludisargs.la
+example_dep_tag_SOURCES = example_dep_tag.cc
+example_dep_tag_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
example_dep_spec_flattener_SOURCES = example_dep_spec_flattener.cc
example_dep_spec_flattener_LDFLAGS = \
libpaludisexamples.a \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/args/libpaludisargs.la
+example_environment_SOURCES = example_environment.cc
+example_environment_LDFLAGS = \
+ libpaludisexamples.a \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/args/libpaludisargs.la
+
built-sources : $(BUILT_SOURCES)
for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
diff --git a/doc/examples/example_dep_tag.cc b/doc/examples/example_dep_tag.cc
new file mode 100644
index 0000000..e511ffb
--- /dev/null
+++ b/doc/examples/example_dep_tag.cc
@@ -0,0 +1,198 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_dep_tag.cc "example_dep_tag.cc" .
+ *
+ * \ingroup g_dep_spec
+ */
+
+/** \example example_dep_tag.cc
+ *
+ * This example demonstrates how to handle dependency tags. It displays
+ * information about the 'security' and 'world' sets.
+ */
+
+#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;
+
+/* We store a set of dep tag categories that we've seen. */
+typedef std::set<std::string> SeenCategories;
+
+namespace
+{
+ /* This visitor is used to display information about a tag. */
+ class TagDisplayer :
+ public ConstVisitor<DepTagVisitorTypes>
+ {
+ public:
+ void visit(const DependencyDepTag & tag)
+ {
+ /* A DependencyDepTag is used during dependency resolution. It
+ * shows why a package is included on a DepList. It has three
+ * additional fields: an optional package ID that pulled in the
+ * entry, an optional dep spec that pulled in the dependency and
+ * an optional set of conditions upon which that dependency is
+ * active. The third field is not used here, since it is too
+ * complicated for this example. */
+ if (tag.package_id())
+ cout << left << setw(20) << " Package ID:" << " " << *tag.package_id() << endl;
+ if (tag.dependency())
+ cout << left << setw(20) << " Dependency:" << " " << *tag.dependency() << endl;
+ }
+
+ void visit(const GLSADepTag & tag)
+ {
+ /* A GLSADepTag is for security advisories. It carries one
+ * additional field, the GLSA's title. */
+ cout << left << setw(20) << " GLSA title:" << " " << tag.glsa_title() << endl;
+ }
+
+ void visit(const GeneralSetDepTag & tag)
+ {
+ /* A GeneralSetDepTag is for general package sets. It carries
+ * one additional field, the source (e.g. a repository or
+ * environment name). */
+ cout << left << setw(20) << " Source:" << " " << tag.source() << endl;
+ }
+
+ void visit(const TargetDepTag &)
+ {
+ /* A TargetDepTag is used to indicate explicit targets when
+ * resolving dependencies. It carries no extra information. */
+ }
+ };
+
+ /* Display information about a named set. */
+ void display_set(
+ const tr1::shared_ptr<const Environment> & env,
+ const SetName & name,
+ SeenCategories & seen_categories)
+ {
+ tr1::shared_ptr<const SetSpecTree::ConstItem> set(env->set(name));
+
+ /* Environment::set can return a zero pointer, if a set is not known. */
+ if (! set)
+ return;
+
+ /* The set isn't necessarily flat. We use DepSpecFlattener to make it
+ * so, rather than writing a full visitor ourselves. We don't need to
+ * supply a package, since a SetSpecTree cannot contain a UseDepSpec. */
+ DepSpecFlattener<SetSpecTree, PackageDepSpec> set_flat(env.get(), tr1::shared_ptr<const PackageID>());
+ set->accept(set_flat);
+
+ cout << "Set '" << name << "':" << endl;
+
+ /* For each item... */
+ for (DepSpecFlattener<SetSpecTree, PackageDepSpec>::ConstIterator s(set_flat.begin()),
+ s_end(set_flat.end()) ; s != s_end ; ++s)
+ {
+ /* Ignore it, if it has no tag. */
+ if (! (*s)->tag())
+ continue;
+
+ cout << " " << **s << ": " << endl;
+
+ /* All dep tags have short text and a category. As well as
+ * displaying the category, we remember it for the categories
+ * summary later on. */
+ cout << left << setw(20) << " Short text:" << " " << (*s)->tag()->short_text() << endl;
+ cout << left << setw(20) << " Category:" << " " << (*s)->tag()->category() << endl;
+ seen_categories.insert((*s)->tag()->category());
+
+ /* We use a visitor to do extra displaying, so that we can display
+ * more detailed information for whatever our tag type is. */
+ TagDisplayer displayer;
+ (*s)->tag()->accept(displayer);
+
+ cout << endl;
+ }
+
+ cout << endl;
+ }
+}
+
+int main(int argc, char * argv[])
+{
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_dep_tag", "EXAMPLE_DEP_TAG_OPTIONS", "EXAMPLE_DEP_TAG_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()));
+
+ SeenCategories seen_categories;
+
+ /* First, tell us about the 'security' set: */
+ display_set(env, SetName("security"), seen_categories);
+
+ /* Then the 'world' set: */
+ display_set(env, SetName("world"), seen_categories);
+
+ /* Now display a summary of seen categories. */
+ cout << "Seen categories:" << endl;
+ for (SeenCategories::const_iterator s(seen_categories.begin()), s_end(seen_categories.end()) ;
+ s != s_end ; ++s)
+ {
+ cout << " " << *s << ":" << endl;
+
+ /* Fetch the category. DepTagCategoryMaker::find_maker returns a
+ * function that creates the category, rather than directly
+ * returning the category. */
+ tr1::shared_ptr<const DepTagCategory> category(
+ DepTagCategoryMaker::get_instance()->find_maker(*s)());
+
+ cout << left << setw(20) << " Visible:" << " " << boolalpha << category->visible() << endl;
+ cout << left << setw(20) << " ID:" << " " << category->id() << endl;
+ cout << left << setw(20) << " Title:" << " " << category->title() << endl;
+ cout << left << setw(20) << " Pre text:" << " " << category->pre_text() << endl;
+ cout << left << setw(20) << " Post text:" << " " << category->post_text() << 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/doc/examples/example_environment.cc b/doc/examples/example_environment.cc
new file mode 100644
index 0000000..5b09235
--- /dev/null
+++ b/doc/examples/example_environment.cc
@@ -0,0 +1,108 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_environment.cc "example_environment.cc" .
+ *
+ * \ingroup g_environment
+ */
+
+/** \example example_environment.cc
+ *
+ * This example demonstrates how to use EnvironmentMaker and the resultant
+ * Environment.
+ */
+
+#include <paludis/paludis.hh>
+#include "example_command_line.hh"
+#include <iostream>
+#include <iomanip>
+
+using namespace paludis;
+using namespace examples;
+
+using std::cout;
+using std::endl;
+using std::left;
+using std::setw;
+
+int main(int argc, char * argv[])
+{
+ int exit_status(0);
+
+ try
+ {
+ CommandLine::get_instance()->run(argc, argv,
+ "example_environment", "EXAMPLE_ENVIRONMENT_OPTIONS", "EXAMPLE_ENVIRONMENT_CMDLINE");
+
+ /* We use EnvironmentMaker to construct an environment from the user's
+ * --environment commandline choice. With an empty string, this uses the
+ * distribution-defined default environment. With a non-empty string, it
+ * is split into two parts upon the first colon (if there is no colon,
+ * the second part is considered empty). The first part is the name of
+ * the environment class to use (e.g. 'paludis', 'portage') and the
+ * second part is passed as parameters to be handled by that
+ * environment's constructor. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(
+ CommandLine::get_instance()->a_environment.argument()));
+
+ /* A lot of the Environment members aren't very useful to clients. The
+ * mask related methods are used by PackageID, and shouldn't usually be
+ * called directly from clients. The system information and mirror
+ * functions are mostly for use by Repository subclasses. That leaves
+ * the package database, sets and (currently, although this may well
+ * change in the future) use flag queries. The package database has its
+ * own examples, so we'll start with sets: */
+
+ tr1::shared_ptr<SetSpecTree::ConstItem> world(env->set(SetName("world")));
+ if (world)
+ {
+ /* See \ref example_dep_tree.cc "example_dep_tree.cc" for how to
+ * make use of this set. */
+ cout << "World set exists" << endl;
+ }
+ else
+ cout << "No world set defined" << endl;
+
+ /* And use flags, for which we need a package IDs: */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)) &
+ query::SupportsAction<InstalledAction>(),
+ qo_order_by_version));
+
+ if (! ids->empty())
+ {
+ UseFlagName u("ruby");
+ cout << "Use flag '" << u << "' for ID '" << **ids->rbegin() << "' is "
+ << (env->query_use(u, **ids->rbegin()) ? "enabled" : "disabled") << 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_status;
+}
+
+
diff --git a/paludis/dep_label.hh b/paludis/dep_label.hh
index 410e09b..9e69f32 100644
--- a/paludis/dep_label.hh
+++ b/paludis/dep_label.hh
@@ -36,6 +36,7 @@
* - \ref example_dep_label.cc "example_dep_label.cc"
* - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
* - \ref example_dep_tree.cc "example_dep_tree.cc" (for specification trees)
+ * - \ref example_dep_tag.cc "example_dep_tag.cc" (for tags)
*/
namespace paludis
diff --git a/paludis/dep_spec.hh b/paludis/dep_spec.hh
index 6be854c..644e3c2 100644
--- a/paludis/dep_spec.hh
+++ b/paludis/dep_spec.hh
@@ -46,6 +46,7 @@
* - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
* - \ref example_dep_label.cc "example_dep_label.cc" (for labels)
* - \ref example_dep_tree.cc "example_dep_tree.cc" (for specification trees)
+ * - \ref example_dep_tag.cc "example_dep_tag.cc" (for tags)
*/
namespace paludis
diff --git a/paludis/dep_tag-fwd.hh b/paludis/dep_tag-fwd.hh
index 2ea1c40..66d3768 100644
--- a/paludis/dep_tag-fwd.hh
+++ b/paludis/dep_tag-fwd.hh
@@ -24,6 +24,12 @@
#include <paludis/util/set-fwd.hh>
#include <paludis/util/attributes.hh>
+/** \file
+ * Forward declarations for paludis/dep_tag.hh .
+ *
+ * \ingroup g_dep_spec
+ */
+
namespace paludis
{
class DepTagCategory;
@@ -44,7 +50,7 @@ namespace paludis
/**
* Tags attached to a DepListEntry.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
*/
typedef Set<DepTagEntry> DepListEntryTags;
}
diff --git a/paludis/dep_tag.cc b/paludis/dep_tag.cc
index bdd28fc..1510f40 100644
--- a/paludis/dep_tag.cc
+++ b/paludis/dep_tag.cc
@@ -29,12 +29,6 @@
#include <libwrapiter/libwrapiter_forward_iterator.hh>
#include <sstream>
-/** \file
- * Implementation for DepTag, DepTagCategory etc.
- *
- * \ingroup grpdeptag
- */
-
using namespace paludis;
template class VirtualConstructor<std::string, tr1::shared_ptr<const DepTagCategory> (*) (),
@@ -61,11 +55,6 @@ template class Set<DepTagEntry>;
namespace
{
- /**
- * Create the DepTagCategory for GLSAs.
- *
- * \ingroup grpdeptag
- */
tr1::shared_ptr<const DepTagCategory>
make_glsa_dep_tag()
{
@@ -77,11 +66,6 @@ namespace
"Please read the advisories carefully and take appropriate action."));
}
- /**
- * Create the DepTagCategory for general sets.
- *
- * \ingroup grpdeptag
- */
tr1::shared_ptr<const DepTagCategory>
make_general_set_dep_tag()
{
@@ -93,11 +77,6 @@ namespace
""));
}
- /**
- * Create the DepTagCategory for dependency sets.
- *
- * \ingroup grpdeptag
- */
tr1::shared_ptr<const DepTagCategory>
make_dependency_set_dep_tag()
{
@@ -109,11 +88,6 @@ namespace
""));
}
- /**
- * Create the DepTagCategory for targets.
- *
- * \ingroup grpdeptag
- */
tr1::shared_ptr<const DepTagCategory>
make_target_dep_tag()
{
diff --git a/paludis/dep_tag.hh b/paludis/dep_tag.hh
index d98a197..a0ba8a1 100644
--- a/paludis/dep_tag.hh
+++ b/paludis/dep_tag.hh
@@ -21,9 +21,16 @@
#define PALUDIS_GUARD_PALUDIS_DEP_TAG_HH 1
/** \file
- * Declarations for the DepTag and DepTagCategory classes.
+ * Declarations for dependency tags.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
+ *
+ * \section Examples
+ *
+ * - \ref example_dep_tag.cc "example_dep_tag.cc" (for tags)
+ * - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
+ * - \ref example_dep_label.cc "example_dep_label.cc" (for labels)
+ * - \ref example_dep_tree.cc "example_dep_tree.cc" (for specification trees)
*/
#include <paludis/dep_tag-fwd.hh>
@@ -46,7 +53,9 @@ namespace paludis
/**
* Visitor class for visiting the different DepTag subclasses.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
+ * \nosubgrouping
+ * \since 0.26
* \see DepTag
*/
struct DepTagVisitorTypes :
@@ -70,7 +79,7 @@ namespace paludis
* \see DepTagCategoryMaker
* \see DepTag
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE DepTagCategory :
@@ -126,8 +135,8 @@ namespace paludis
/**
* Thrown if DepTagCategoryMaker cannot find the named DepTagCategory.
*
- * \ingroup grpexceptions
- * \ingroup grpdeptag
+ * \ingroup g_exceptions
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE NoSuchDepTagCategory :
@@ -145,7 +154,8 @@ namespace paludis
/**
* Virtual constructor for accessing DepTagCategory instances.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
+ * \nosubgrouping
*/
class PALUDIS_VISIBLE DepTagCategoryMaker :
public VirtualConstructor<std::string, tr1::shared_ptr<const DepTagCategory> (*) (),
@@ -158,12 +168,6 @@ namespace paludis
DepTagCategoryMaker();
};
- class DepTag;
- class GLSADepTag;
- class GeneralSetDepTag;
- class DependencyDepTag;
- class TargetDepTag;
-
/**
* A DepTag can be associated with a PackageDepSpec, and is transferred
* onto any associated DepListEntry instances.
@@ -171,7 +175,7 @@ namespace paludis
* It is used for tagging dep list entries visually, for example to
* indicate an associated GLSA.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE DepTag :
@@ -213,7 +217,7 @@ namespace paludis
/**
* DepTag subclass for GLSAs.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE GLSADepTag :
@@ -247,7 +251,7 @@ namespace paludis
/**
* DepTag subclass for general sets.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE GeneralSetDepTag :
@@ -277,7 +281,7 @@ namespace paludis
/**
* DepTag subclass for dependencies.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE DependencyDepTag :
@@ -314,7 +318,8 @@ namespace paludis
const tr1::shared_ptr<const PackageDepSpec> dependency() const;
/**
- * The AllDepSpecs and UseDepSpecs that our dependency is conditional upon.
+ * The AllDepSpec instances and UseDepSpec instances that our dependency
+ * is conditional upon.
*/
const tr1::shared_ptr<const DependencySpecTree::ConstItem> conditions() const;
};
@@ -322,7 +327,7 @@ namespace paludis
/**
* DepTag subclass for explicit targets.
*
- * \ingroup grpdeptag
+ * \ingroup g_dep_spec
* \nosubgrouping
*/
class PALUDIS_VISIBLE TargetDepTag :
diff --git a/paludis/dep_tag.sr b/paludis/dep_tag.sr
index 31e1efb..2daf201 100644
--- a/paludis/dep_tag.sr
+++ b/paludis/dep_tag.sr
@@ -16,7 +16,7 @@ make_class_DepTagEntry()
* to outside clients.
*
* \see DepListEntry
- * \ingroup grpdepresolver
+ * \ingroup g_dep_list
* \nosubgrouping
*/
END
diff --git a/paludis/dep_tree.hh b/paludis/dep_tree.hh
index fa48a5c..7f6cf09 100644
--- a/paludis/dep_tree.hh
+++ b/paludis/dep_tree.hh
@@ -34,6 +34,7 @@
* - \ref example_dep_tree.cc "example_dep_tree.cc" (for specification trees)
* - \ref example_dep_spec.cc "example_dep_spec.cc" (for specifications)
* - \ref example_dep_label.cc "example_dep_label.cc" (for labels)
+ * - \ref example_dep_tag.cc "example_dep_tag.cc" (for tags)
*/
namespace paludis
diff --git a/paludis/distribution-fwd.hh b/paludis/distribution-fwd.hh
index cb45444..c04450a 100644
--- a/paludis/distribution-fwd.hh
+++ b/paludis/distribution-fwd.hh
@@ -20,6 +20,12 @@
#ifndef PALUDIS_GUARD_PALUDIS_DISTRIBUTION_FWD_HH
#define PALUDIS_GUARD_PALUDIS_DISTRIBUTION_FWD_HH 1
+/** \file
+ * Forward declarations for paludis/distribution.hh .
+ *
+ * \ingroup g_dep_spec
+ */
+
namespace paludis
{
class Distribution;
diff --git a/paludis/distribution.hh b/paludis/distribution.hh
index f33584a..1116c8e 100644
--- a/paludis/distribution.hh
+++ b/paludis/distribution.hh
@@ -28,6 +28,17 @@
#include <paludis/util/instantiation_policy.hh>
#include <paludis/util/tr1_memory.hh>
+/** \file
+ * Declarations for distributions.
+ *
+ * \ingroup g_distribution
+ *
+ * \section Examples
+ *
+ * - None at this time. The Distribution classes are of little direct use to
+ * clients; they are mainly used by Repository and Environment implementations.
+ */
+
namespace paludis
{
#include <paludis/distribution-sr.hh>
@@ -35,8 +46,9 @@ namespace paludis
/**
* Thrown if an invalid distribution file is encountered.
*
- * \ingroup grpdistributions
- * \ingroup grpexceptions
+ * \ingroup g_distribution
+ * \ingroup g_exceptions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE DistributionConfigurationError :
@@ -54,7 +66,14 @@ namespace paludis
/**
* Fetch information about a distribution.
*
- * \ingroup grpdistributions
+ * Paludis avoids hardcoding certain distribution-related information to
+ * make things easier for other distributions. Instead, DistributionData
+ * is used to fetch a Distribution class instance. The
+ * distribution_from_string method is almost always called with the return
+ * value of Environment::default_distribution as its parameter.
+ *
+ * \ingroup g_distribution
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE DistributionData :
diff --git a/paludis/distribution.sr b/paludis/distribution.sr
index 8ea6d77..c8e97a9 100644
--- a/paludis/distribution.sr
+++ b/paludis/distribution.sr
@@ -34,6 +34,8 @@ make_class_Distribution()
* Information about a distribution.
*
* \see DistributionData
+ * \ingroup g_distribution
+ * \since 0.26
* \nosubgrouping
*/
END
diff --git a/paludis/environment-fwd.hh b/paludis/environment-fwd.hh
index cbd27d6..946ed3e 100644
--- a/paludis/environment-fwd.hh
+++ b/paludis/environment-fwd.hh
@@ -21,31 +21,22 @@
#define PALUDIS_GUARD_PALUDIS_ENVIRONMENT_FWD_HH 1
#include <paludis/util/sequence-fwd.hh>
-#include <paludis/util/options-fwd.hh>
#include <paludis/util/attributes.hh>
-#include <paludis/util/sequence-fwd.hh>
-#include <iosfwd>
+#include <string>
+
+/** \file
+ * Forward declarations for paludis/environment.hh .
+ *
+ * \ingroup g_environment
+ */
namespace paludis
{
- class PackageDatabase;
-
-#include <paludis/environment-se.hh>
-
- /**
- * Options for Environment::mask_reasons().
- *
- * \see Environment
- * \see MaskReasonsOption
- * \ingroup grpenvironment
- */
- typedef Options<MaskReasonsOption> MaskReasonsOptions;
-
/**
* A collection of mirror prefixes.
*
* \see Environment
- * \ingroup grpenvironment
+ * \ingroup g_environment
*/
typedef Sequence<std::string> MirrorsSequence;
diff --git a/paludis/environment.cc b/paludis/environment.cc
index 2dc979c..4094c44 100644
--- a/paludis/environment.cc
+++ b/paludis/environment.cc
@@ -24,8 +24,6 @@
using namespace paludis;
-#include <paludis/environment-se.cc>
-
template class Sequence<std::string>;
Environment::~Environment()
diff --git a/paludis/environment.hh b/paludis/environment.hh
index 9186bf8..a3102ed 100644
--- a/paludis/environment.hh
+++ b/paludis/environment.hh
@@ -31,11 +31,16 @@
#include <paludis/dep_tree.hh>
#include <paludis/package_id-fwd.hh>
#include <paludis/mask-fwd.hh>
+#include <paludis/package_database-fwd.hh>
/** \file
* Declarations for the Environment class.
*
- * \ingroup grpenvironment
+ * \ingroup g_environment
+ *
+ * \section Examples
+ *
+ * - \ref example_environment.cc "example_environment.cc"
*/
namespace paludis
@@ -49,11 +54,12 @@ namespace paludis
* instances.
*
* Environment itself is purely an interface class. Actual Environment
- * implementations descend from EnvironmentImplementation, which provides
- * much of the common implementation details. EnvironmentMaker is often
- * used to create the appropriate Environment subclass for an application.
+ * implementations usually descend from EnvironmentImplementation, which
+ * provides much of the common implementation details. EnvironmentMaker is
+ * often used to create the appropriate Environment subclass for an
+ * application.
*
- * \ingroup grpenvironment
+ * \ingroup g_environment
* \see PackageDatabase
* \see EnvironmentMaker
* \see EnvironmentImplementation
@@ -98,6 +104,9 @@ namespace paludis
/**
* Do we accept a particular license for a particular package?
+ *
+ * Used by PackageID implementations. Generally PackageID's masks methods
+ * should be used rather than calling this directly.
*/
virtual bool accept_license(const std::string &, const PackageID &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
@@ -106,6 +115,9 @@ namespace paludis
* Do we accept any of the specified keywords for a particular package?
*
* If the collection includes "*", should return true.
+ *
+ * Used by PackageID implementations. Generally PackageID's masks methods
+ * should be used rather than calling this directly.
*/
virtual bool accept_keywords(tr1::shared_ptr<const KeywordNameSet>, const PackageID &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
@@ -114,6 +126,9 @@ namespace paludis
* Do we have a 'breaks' mask for a particular package?
*
* Returns a zero pointer if no.
+ *
+ * Used by PackageID implementations. Generally PackageID's masks methods
+ * should be used rather than calling this directly.
*/
virtual const tr1::shared_ptr<const Mask> mask_for_breakage(const PackageID &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
@@ -122,6 +137,9 @@ namespace paludis
* Do we have a 'user' mask for a particular package?
*
* Returns a zero pointer if no.
+ *
+ * Used by PackageID implementations. Generally PackageID's masks methods
+ * should be used rather than calling this directly.
*/
virtual const tr1::shared_ptr<const Mask> mask_for_user(const PackageID &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
@@ -131,6 +149,9 @@ namespace paludis
*
* This is only applied to repository and profile style masks, not
* keywords, licences etc. If true, user_mask shouldn't be used.
+ *
+ * Used by PackageID implementations. Generally PackageID's masks methods
+ * should be used rather than calling this directly.
*/
virtual bool unmasked_by_user(const PackageID &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
@@ -208,7 +229,8 @@ namespace paludis
* Used by InstallTask to decide whether to exec() after installing
* a package.
*/
- virtual bool is_paludis_package(const QualifiedPackageName &) const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
+ virtual bool is_paludis_package(const QualifiedPackageName &) const
+ PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
///\}
diff --git a/paludis/environment.se b/paludis/environment.se
deleted file mode 100644
index e4bf5c6..0000000
--- a/paludis/environment.se
+++ /dev/null
@@ -1,21 +0,0 @@
-#!/bin/bash
-# vim: set sw=4 sts=4 et ft=sh :
-
-make_enum_MaskReasonsOption()
-{
- prefix mro
-
- key mro_override_unkeyworded "Ignore keyword masks for unkeyworded packages"
- key mro_override_tilde_keywords "Pretend packages with keyword ~foo also have keyword foo"
-
- doxygen_comment << "END"
- /**
- * Options for Environment::mask_reasons().
- *
- * \see MaskReasonsOptions
- * \see Environment
- * \ingroup grpenvironment
- */
-END
-}
-
diff --git a/paludis/environment_implementation.hh b/paludis/environment_implementation.hh
index cb60ebc..c530767 100644
--- a/paludis/environment_implementation.hh
+++ b/paludis/environment_implementation.hh
@@ -23,19 +23,33 @@
#include <paludis/environment.hh>
#include <paludis/package_id-fwd.hh>
+/** \file
+ * Declarations for the Environment class.
+ *
+ * \ingroup g_environment
+ *
+ * \section Examples
+ *
+ * - None at this time. The EnvironmentImplementation class is of no relevance
+ * to clients.
+ */
+
namespace paludis
{
/**
* Simplifies implementing the Environment interface.
*
- * \ingroup grpenvironment
+ * Most Environment subclasses derive from this class, rather than directly
+ * from the abstract base. It provides default implementations for many
+ * methods.
+ *
+ * \ingroup g_environment
* \see Environment
*/
class PALUDIS_VISIBLE EnvironmentImplementation :
public Environment
{
protected:
-
virtual tr1::shared_ptr<SetSpecTree::ConstItem> local_set(const SetName &) const
PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
diff --git a/paludis/files.m4 b/paludis/files.m4
index e888974..b331b97 100644
--- a/paludis/files.m4
+++ b/paludis/files.m4
@@ -21,7 +21,7 @@ add(`dep_spec_flattener', `hh', `cc')
add(`dep_tree', `hh', `cc', `fwd')
add(`dep_tag', `hh', `cc', `fwd', `sr')
add(`distribution', `hh', `cc', `fwd', `sr')
-add(`environment', `hh', `fwd', `cc', `se')
+add(`environment', `hh', `fwd', `cc')
add(`environment_implementation', `hh', `cc')
add(`environment_maker', `hh', `cc')
add(`find_unused_packages_task', `hh', `cc')
diff --git a/ruby/qa.cc b/ruby/qa.cc
index 924d7f6..b0b8cad 100644
--- a/ruby/qa.cc
+++ b/ruby/qa.cc
@@ -105,7 +105,7 @@ namespace
try
{
int mr = NUM2INT(qa_check_property);
- if (mr < 0 || mr >= last_mro)
+ if (mr < 0 || mr >= last_qacp)
rb_raise(rb_eArgError, "QACheckProperty out of range");
*m_ptr += static_cast<QACheckProperty>(mr);
return Qnil;