aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-04-19 16:47:47 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-04-19 16:47:47 +0000
commit0279d59df48f32bc7e1172d5b2df7000cb518e78 (patch)
treef24a2fa7802931cb64ccfdf30682fe0e0d14dd18
parentd03c56fa8e1053678d59f57ba95e8639c8d05c8b (diff)
downloadpaludis-0279d59df48f32bc7e1172d5b2df7000cb518e78.tar.gz
paludis-0279d59df48f32bc7e1172d5b2df7000cb518e78.tar.xz
First part of the documentation rework, plus minor formatting and code style fixes. More to come.
-rw-r--r--doc/doc_main.doxygen259
-rw-r--r--doc/doc_namespaces.doxygen9
-rw-r--r--paludis/about.hh.in74
-rw-r--r--paludis/about_TEST.cc6
-rw-r--r--paludis/config_file.cc6
-rw-r--r--paludis/config_file.hh23
-rw-r--r--paludis/config_file_TEST.cc86
-rw-r--r--paludis/default_config.cc6
-rw-r--r--paludis/default_config.hh60
-rw-r--r--paludis/dep_atom.cc6
-rw-r--r--paludis/dep_atom.hh36
-rw-r--r--paludis/dep_atom_TEST.cc12
-rw-r--r--paludis/dep_atom_dumper.cc6
-rw-r--r--paludis/dep_atom_dumper.hh4
-rw-r--r--paludis/dep_atom_dumper_TEST.cc5
-rw-r--r--paludis/dep_atom_flattener.cc6
-rw-r--r--paludis/dep_atom_flattener.hh11
-rw-r--r--paludis/dep_atom_pretty_printer.cc6
-rw-r--r--paludis/dep_atom_pretty_printer.hh12
-rw-r--r--paludis/dep_lexer.cc7
-rw-r--r--paludis/dep_lexer.hh22
-rw-r--r--paludis/dep_lexer_TEST.cc16
-rw-r--r--paludis/dep_parser.cc25
-rw-r--r--paludis/dep_parser.hh47
-rw-r--r--paludis/dep_parser_TEST.cc24
-rw-r--r--paludis/dep_tag.cc23
-rw-r--r--paludis/dep_tag.hh90
27 files changed, 584 insertions, 303 deletions
diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index aa3d30f..8261b11 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -1,208 +1,113 @@
/* vim: set ft=cpp tw=80 sw=4 et : */
-/** \defgroup DepResolver Dependency parsing and resolution
-Dependency parsing and resolution.
+// ----- Top Level Groups -----
-Dependency resolution is handled in stages. We convert a dependency string
-into a tree structure, and then define a visitor over this structure.
+/** \defgroup grplibpaludis Main Paludis library
+ */
-\section DepResolverImportant Important Classes
+/** \defgroup grplibpaludisutil Paludis utilities library
+ */
-- paludis::DepList creates and holds dependency lists
-- paludis::DepParser turns a dependency string into a paludis::DepAtom
- heirarchy.
-*/
+/** \defgroup grplibpaludisqa Paludis QA library
+ */
-/** \defgroup Environment Environment
-Environment.
+/** \defgroup grptestcases Test cases
+ */
-These classes represent the environment in which paludis is running.
+/** \defgroup grpexceptions Exceptions
+ */
-\section EnvironmentImportant Important Classes
+// ----- grplibpaludis Subgroups -----
-- paludis::Environment represents an environment.
-- paludis::DefaultEnvironment represents the usual environment that should
- be used when writing normal programs (other paludis::Environment
- descendents exist, e.g. for testing).
-*/
+/** \defgroup grpdependencies Dependencies
+ *
+ * \ingroup grplibpaludis
+ */
-/** \defgroup Database Package database functionality
-Package database functionality.
+/** \defgroup grpabout About Paludis
+ *
+ * \ingroup grplibpaludis
+ */
-These classes provide checked representations for common data types, as
-well as the core queryable package database functionality.
+/** \defgroup grpconfigfile Configuration files
+ *
+ * \ingroup grplibpaludis
+ */
-\section DatabaseImportant Important Classes
+/** \defgroup grpenvironment Environment
+ *
+ * \ingroup grplibpaludis
+ */
-- paludis::PackageDatabase represents a package database, which
- is queryable and holds zero or more paludis::Repository instances.
+// ----- grpconfigfile Subgroups -----
-\ingroup Environment
-*/
+/** \defgroup grpkvconfigfile Key/Value configuration file
+ *
+ * \ingroup grpconfigfile
+ */
+/** \defgroup grplineconfigfile Line configuration file
+ *
+ * \ingroup grpconfigfile
+ */
-/** \defgroup Utility Utilities
-Utilities.
+/** \defgroup grpadvisoryconfigfile Security advisory file
+ *
+ * \ingroup grpconfigfile
+ */
-Various miscellaneous utilities.
-*/
+// ----- grpenvironment Subgroups -----
-/** \defgroup Exception Exception handling
-Exception handling.
+/** \defgroup grpdefaultenvironment Default environment
+ *
+ * \ingroup grpenvironment
+ */
-All exceptions thrown from paludis should be a subclass of
-paludis::Exception, which provides a message and (via libebt) a backtrace
-giving details of the error. It is probably wise to also check for
-std::exception when writing error handling code.
+// ----- grpdefaultenvironment Subgroups -----
-\section ExceptionImportant Important classes
+/** \defgroup grpdefaultconfig Default configuration
+ *
+ * \ingroup grpdefaultenvironment
+ */
-- paludis::Exception is the base exception class. All exceptions thrown
- by paludis should be descended from this class (although it's best to
- check for std::exception too just in case).
+// ----- grpdepatoms Subgroups -----
-\ingroup Utility
-*/
+/** \defgroup grpdepatomdumper Dep atom dumper
+ *
+ * \ingroup grpdepatoms
+ */
-/** \defgroup Args Command line argument handling
-Command line handling for a program.
+/** \defgroup grpdepatomflattener Dep atom flattener
+ *
+ * \ingroup grpdepatoms
+ */
-Command line handling for a program is done via a subclass of ArgsHandler.
-The class will have member variables of type ArgsGroup to handle groups of
-related arguments, and member variables of subtypes of ArgsOption to handle
-individual switches.
+/** \defgroup grpdepatomprettyprinter Dep atom pretty printer
+ *
+ * \ingroup grpdepatoms
+ */
-\ingroup Utility
-*/
+// ----- grpdependencies Subgroups -----
-/** \defgroup Pointer Pointers
-Pointers.
+/** \defgroup grpdepresolver Dependency resolution
+ *
+ * \ingroup grpdependencies
+ */
-We use shared pointers in various places. Different policies are available
-for different reference count models.
+/** \defgroup grpdepatoms Dependency atoms
+ *
+ * \ingroup grpdependencies
+ */
-\section PointerImportant Important Classes
+/** \defgroup grpdepparser Dependency parsing
+ *
+ * \ingroup grpdependencies
+ */
-- paludis::CountedPtr is used for reference counted pointers.
-
-\ingroup Utility
-*/
-
-/** \defgroup Tokeniser Tokeniser
-Tokeniser.
-
-The paludis::Tokeniser class provides a way of splitting strings into
-smaller strings.
-
-\section TokeniserImportant Important Classes
-
-- paludis::Tokeniser is the main class.
-
-\ingroup Utility
-*/
-
-/** \defgroup Filesystem Filesystem wrapper utilities
-Filesystem wrapper utilities.
-
-The C++ standard library doesn't provide anything for working with
-filesystem entries or directories. Rather than repeatedly making calls
-to stat(2) and opendir(3) all over the place (or using the bloatware
-utilities from Boost), we provide a few lightweight wrapper classes.
-
-\section FilesystemImportant Important Classes
-
-- paludis::FSEntry represents a filesystem entry.
-- paludis::DirIterator is an iterator for directories.
-- paludis::IsFileWithExtension can be used as a functor to determine
- whether a paludis::FSEntry instance is a file with certain attributes.
-
-\ingroup Utility
-*/
-
-/** \defgroup PStream Process handling
-Process handling.
-
-The paludis::PStream class can be used to execute a process and get its
-standard output.
-
-\section PStreamImportant Important Classes
-
-- paludis::PStream is a front-end std::istream descendent for process
- invokation.
-
-\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::TransformInsertIterator (which can be created via
- paludis::transform_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 Visitor Visitor pattern
-Visitor pattern.
-
-See \ref GoF for how visitors work. See the test cases for how to use
-it.
-
-\ingroup Utility
-*/
-
-/** \defgroup VirtualConstructor Virtual constructors
-Visitor pattern.
-
-See \ref GoF for how virtual constructors (called "Factory Methods" there)
-work. See the test cases for how to use it.
-
-\ingroup Utility
-*/
-
-/** \defgroup ConfigFile Configuration handling
-Configuration handling.
-
-The paludis::ConfigFile class is a handler for generic configuration files
-using a general line-oriented, comments start with a # format. Various
-subclasses provide interfaces for different file formats.
-
-\section ConfigFileImportant Important Classes
-
-- paludis::KeyValueFile represents a configuration file containing
- KEY="value" type statements.
-- paludis::LineConfigFile represents a configuration file containing
- lines of text.
-*/
-
-/** \defgroup Test Test cases and framework
-Test cases and framework.
-
-Test cases are classes that are descended from TestCase. Declaring an
-instance of a TestCase subclass will register it with the test case
-list.
-*/
-
-/** \defgroup QA QA Checks
-QA Checks.
-
-Various QA checks that can be applied to packages or ebuilds.
-*/
+// ----- grpdepparser Subgroups -----
+/** \defgroup grpdeplexer Dependency lexing
+ *
+ * \ingroup grpdepparser
+ */
diff --git a/doc/doc_namespaces.doxygen b/doc/doc_namespaces.doxygen
index c26b6eb..8b8164f 100644
--- a/doc/doc_namespaces.doxygen
+++ b/doc/doc_namespaces.doxygen
@@ -12,6 +12,10 @@
* \ingroup Test
*/
+/** \namespace paludis
+ * Paludis library code.
+ */
+
/** \namespace paludis::args
* Commandline argument handling.
*
@@ -23,8 +27,3 @@
*
* \ingroup Args
*/
-
-/** \namespace paludis
- * Paludis library code.
- */
-
diff --git a/paludis/about.hh.in b/paludis/about.hh.in
index 2bf4eab..cd171ec 100644
--- a/paludis/about.hh.in
+++ b/paludis/about.hh.in
@@ -25,43 +25,93 @@
/** \file
* Defines constants giving the Paludis version number and information about
* how Paludis was built.
+ *
+ * \ingroup grpabout
*/
-/// The package name (eg Paludis)
+/**
+ * The package name (eg Paludis).
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_PACKAGE "@PACKAGE@"
-/// The major version (eg 0.4.1 -> 0)
+/**
+ * The major version (eg 0.4.1 -> 0).
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_VERSION_MAJOR @VERSION_MAJOR@
-/// The minor version (eg 0.4.1 -> 4)
+/**
+ * The minor version (eg 0.4.1 -> 4).
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_VERSION_MINOR @VERSION_MINOR@
-/// The micro version (eg 0.4.1 -> 1)
+/**
+ * The micro version (eg 0.4.1 -> 1).
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_VERSION_MICRO @VERSION_MICRO@
-/// The version, two digits per part (eg 1.3.5 -> 10305)
+/**
+ * The version, two digits per part (eg 1.3.5 -> 10305).
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_VERSION ((100 * 100 * PALUDIS_VERSION_MAJOR) \
+ (100 * PALUDIS_VERSION_MINOR) + PALUDIS_VERSION_MICRO)
-/// The subversion revision, if applicable (eg "65" or "65M" or "").
+/**
+ * The subversion revision, if applicable (eg "65" or "65M" or "").
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_SUBVERSION_REVISION "@SVNVERSION@"
-/// The CXXFLAGS used to build Paludis.
+/**
+ * The CXXFLAGS used to build Paludis.
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_BUILD_CXXFLAGS "@CXXFLAGS@"
-/// The LDFLAGS used to build Paludis.
+/**
+ * The LDFLAGS used to build Paludis.
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_BUILD_LDFLAGS "@LDFLAGS@"
-/// The compiler used to build Paludis.
+/**
+ * The compiler used to build Paludis.
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_BUILD_CXX "@CXX@"
-/// The user who built Paludis.
+/**
+ * The user who built Paludis.
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_BUILD_USER "@BUILDUSER@"
-/// The host on which Paludis was built.
+/**
+ * The host on which Paludis was built.
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_BUILD_HOST "@BUILDHOST@"
-/// The date when Paludis was built.
+/**
+ * The date when Paludis was built.
+ *
+ * \ingroup grpabout
+ */
#define PALUDIS_BUILD_DATE "@BUILDDATE@"
#endif
diff --git a/paludis/about_TEST.cc b/paludis/about_TEST.cc
index d8faa47..5126476 100644
--- a/paludis/about_TEST.cc
+++ b/paludis/about_TEST.cc
@@ -28,7 +28,7 @@ using namespace paludis;
* \file
* Test cases for about.hh .
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
namespace test_cases
@@ -36,7 +36,7 @@ namespace test_cases
/**
* \test Version tests.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct VersionTest : TestCase
{
@@ -65,7 +65,7 @@ namespace test_cases
/**
* \test Build info tests.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct BuildInfoTest : TestCase
{
diff --git a/paludis/config_file.cc b/paludis/config_file.cc
index 732d5e8..0633e8e 100644
--- a/paludis/config_file.cc
+++ b/paludis/config_file.cc
@@ -24,6 +24,12 @@
#include <paludis/util/stringify.hh>
#include <paludis/util/strip.hh>
+/** \file
+ * Implementation for config_file.hh classes.
+ *
+ * \ingroup grpconfigfile
+ */
+
using namespace paludis;
ConfigFileError::ConfigFileError(const std::string & message) throw () :
diff --git a/paludis/config_file.hh b/paludis/config_file.hh
index a121133..e971caf 100644
--- a/paludis/config_file.hh
+++ b/paludis/config_file.hh
@@ -31,8 +31,7 @@
/** \file
* Declarations for the ConfigFile classes.
*
- * \ingroup ConfigFile
- * \ingroup Exception
+ * \ingroup grpconfigfile
*/
namespace paludis
@@ -40,8 +39,8 @@ namespace paludis
/**
* Thrown if an error occurs when reading a ConfigFile.
*
- * \ingroup Exception
- * \ingroup ConfigFile
+ * \ingroup grpexceptions
+ * \ingroup grpconfigfile
*/
class ConfigFileError : public ConfigurationError
{
@@ -57,7 +56,7 @@ namespace paludis
* starting with a # being ignored and leading and trailing whitespace
* being discarded.
*
- * \ingroup ConfigFile
+ * \ingroup grpconfigfile
*/
class ConfigFile :
paludis::InstantiationPolicy<ConfigFile, instantiation_method::NonCopyableTag>
@@ -132,7 +131,7 @@ namespace paludis
* A LineConfigFile is a ConfigFile that provides access to the
* normalised lines. Do not subclass.
*
- * \ingroup ConfigFile
+ * \ingroup grplineconfigfile
*/
class LineConfigFile : protected ConfigFile
{
@@ -184,8 +183,8 @@ namespace paludis
* A KeyValueConfigFileError is thrown if bad data is encountered in
* a ConfigFile.
*
- * \ingroup ConfigFile
- * \ingroup Exception
+ * \ingroup grpkvconfigfile
+ * \ingroup grpexceptions
*/
class KeyValueConfigFileError : public ConfigurationError
{
@@ -201,7 +200,7 @@ namespace paludis
* A KeyValueConfigFile is a ConfigFile that provides access to the
* normalised lines. Do not subclass.
*
- * \ingroup ConfigFile
+ * \ingroup grpkvconfigfile
*/
class KeyValueConfigFile : protected ConfigFile
{
@@ -294,8 +293,8 @@ namespace paludis
* An AdvisoryFileError is thrown if bad data is encountered in
* a ConfigFile.
*
- * \ingroup ConfigFile
- * \ingroup Exception
+ * \ingroup grpadvisoryconfigfile
+ * \ingroup grpexceptions
*/
class AdvisoryFileError : public ConfigurationError
{
@@ -317,7 +316,7 @@ namespace paludis
* Valid header items are:
* Affected, Bug-Url, Committed-By, Id, Reviewed-By, Unaffected, Url
*
- * \ingroup ConfigFile
+ * \ingroup grpadvisoryconfigfile
*/
class AdvisoryFile : protected ConfigFile
diff --git a/paludis/config_file_TEST.cc b/paludis/config_file_TEST.cc
index a2782dd..0ac913a 100644
--- a/paludis/config_file_TEST.cc
+++ b/paludis/config_file_TEST.cc
@@ -32,48 +32,66 @@ using namespace paludis;
/** \file
* Test cases for config_file.hh .
*
- * \ingroup Test
- * \ingroup ConfigFile
+ * \ingroup grptestcases
+ * \ingroup grpconfigfile
*/
-#ifndef DOXYGEN
-class TestFile : protected ConfigFile
+namespace
{
- public:
- TestFile(std::istream * const stream) :
- ConfigFile(stream)
- {
- need_lines();
- }
+ /**
+ * A ConfigFile descendent for use in tests.
+ *
+ * \ingroup grptestcases
+ */
+ class TestFile : protected ConfigFile
+ {
+ public:
+ /**
+ * Constructor.
+ */
+ TestFile(std::istream * const stream) :
+ ConfigFile(stream)
+ {
+ need_lines();
+ }
- TestFile(const std::string & filename) :
- ConfigFile(filename)
- {
- need_lines();
- }
+ /**
+ * Constructor.
+ */
+ TestFile(const std::string & filename) :
+ ConfigFile(filename)
+ {
+ need_lines();
+ }
- TestFile(const FSEntry & filename) :
- ConfigFile(filename)
- {
- need_lines();
- }
+ /**
+ * Constructor.
+ */
+ TestFile(const FSEntry & filename) :
+ ConfigFile(filename)
+ {
+ need_lines();
+ }
- mutable std::vector<std::string> lines;
+ /**
+ * Our lines.
+ */
+ mutable std::vector<std::string> lines;
- protected:
- void accept_line(const std::string & s) const
- {
- lines.push_back(s);
- }
-};
-#endif
+ protected:
+ void accept_line(const std::string & s) const
+ {
+ lines.push_back(s);
+ }
+ };
+}
namespace test_cases
{
/**
* \test Test ConfigFile.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct ConfigFileTest : TestCase
{
@@ -104,7 +122,7 @@ namespace test_cases
/**
* \test Test ConfigFile with file opening.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct ConfigFileOpenFileTest : TestCase
{
@@ -136,7 +154,7 @@ namespace test_cases
/**
* \test Test LineConfigFile.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct LineConfigFileTest : TestCase
{
@@ -169,7 +187,7 @@ namespace test_cases
/**
* \test Test KeyValueConfigFile basics.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct KeyValueConfigFileTest : TestCase
{
@@ -197,7 +215,7 @@ namespace test_cases
/**
* \test Test KeyValueConfigFile variables.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct KeyValueConfigFileVarsTest : TestCase
{
@@ -242,7 +260,7 @@ namespace test_cases
/**
* \test Test KeyValueConfigFile errors.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct KeyValueConfigFileErrorsTest : TestCase
{
diff --git a/paludis/default_config.cc b/paludis/default_config.cc
index 6ced0c6..9f40b01 100644
--- a/paludis/default_config.cc
+++ b/paludis/default_config.cc
@@ -34,6 +34,12 @@
#include <sstream>
#include <ctype.h>
+/** \file
+ * Implementation of default_config.hh classes.
+ *
+ * \ingroup grpdefaultconfig
+ */
+
using namespace paludis;
DefaultConfigError::DefaultConfigError(const std::string & msg) throw () :
diff --git a/paludis/default_config.hh b/paludis/default_config.hh
index 2703d97..dd30a8e 100644
--- a/paludis/default_config.hh
+++ b/paludis/default_config.hh
@@ -32,13 +32,20 @@
#include <vector>
#include <string>
+/** \file
+ * Declarations for the DefaultConfig class and related utilities.
+ *
+ * \ingroup grpdefaultconfig
+ */
+
namespace paludis
{
/**
* A DefaultConfigError is thrown if a configuration error is encountered
* by DefaultConfig.
*
- * \ingroup Exception
+ * \ingroup grpexceptions
+ * \ingroup grpdefaultconfig
*/
class DefaultConfigError : public ConfigurationError
{
@@ -51,6 +58,10 @@ namespace paludis
/**
* Keys for RepositoryConfigEntry.
+ *
+ * \see RepositoryConfigEntry
+ *
+ * \ingroup grpdefaultconfig
*/
enum RepositoryConfigEntryKeys
{
@@ -62,6 +73,10 @@ namespace paludis
/**
* Tag for RepositoryConfigEntry.
+ *
+ * \see RepositoryConfigEntry
+ *
+ * \ingroup grpdefaultconfig
*/
struct RepositoryConfigEntryTag :
SmartRecordTag<comparison_mode::FullComparisonTag,
@@ -75,11 +90,17 @@ namespace paludis
/**
* Holds an entry in a DefaultConfig's repository configuration data.
+ *
+ * \ingroup grpdefaultconfig
*/
typedef MakeSmartRecord<RepositoryConfigEntryTag>::Type RepositoryConfigEntry;
/**
* Keys for UseConfigEntry.
+ *
+ * \see UseConfigEntry
+ *
+ * \ingroup grpdefaultconfig
*/
enum UseConfigEntryKeys
{
@@ -90,6 +111,10 @@ namespace paludis
/**
* Tag for UseConfigEntry.
+ *
+ * \see UseConfigEntry
+ *
+ * \ingroup grpdefaultconfig
*/
struct UseConfigEntryTag :
SmartRecordTag<comparison_mode::NoComparisonTag, void>,
@@ -101,13 +126,17 @@ namespace paludis
};
/**
- * An entry in a DefaultConfig's use configuration data.
+ * An entry in a DefaultConfig's use configuration data.
+ *
+ * \ingroup grpdefaultconfig
*/
typedef MakeSmartRecord<UseConfigEntryTag>::Type UseConfigEntry;
/**
* DefaultConfig is used by DefaultEnvironment to access the user's
* configuration settings from on-disk configuration files.
+ *
+ * \ingroup grpdefaultconfig
*/
class DefaultConfig :
public InstantiationPolicy<DefaultConfig, instantiation_method::SingletonAsNeededTag>
@@ -160,6 +189,9 @@ namespace paludis
*/
static void set_config_suffix(const std::string &);
+ ///\name Repositories
+ ///{
+
/**
* An iterator for our repositories.
*/
@@ -181,6 +213,11 @@ namespace paludis
return _repos.end();
}
+ ///}
+
+ ///\name Keywords
+ ///{
+
/**
* Iterate over our package.keywords entries.
*/
@@ -236,6 +273,11 @@ namespace paludis
return _default_keywords.end();
}
+ ///}
+
+ ///\name Licenses
+ ///{
+
/**
* Iterate over our licenses entries.
*/
@@ -291,6 +333,11 @@ namespace paludis
return _default_licenses.end();
}
+ ///}
+
+ ///\name Masks
+ ///{
+
/**
* Iterator over user package masks.
*/
@@ -351,6 +398,11 @@ namespace paludis
return _empty_masks.end();
}
+ ///}
+
+ ///\name Use
+ ///{
+
/**
* Iterator to the start of the use configuration.
*/
@@ -402,6 +454,7 @@ namespace paludis
{
return _default_use.end();
}
+ ///}
/**
* Our bashrc files.
@@ -416,6 +469,9 @@ namespace paludis
return _paludis_command;
}
+ /**
+ * Set the paludis command.
+ */
void set_paludis_command(const std::string & s)
{
_paludis_command = s;
diff --git a/paludis/dep_atom.cc b/paludis/dep_atom.cc
index 33e7539..790ebcd 100644
--- a/paludis/dep_atom.cc
+++ b/paludis/dep_atom.cc
@@ -19,6 +19,12 @@
#include <paludis/dep_atom.hh>
+/** \file
+ * Implementation for dep_atom.hh things.
+ *
+ * \ingroup grpdepatoms
+ */
+
using namespace paludis;
DepAtom::DepAtom()
diff --git a/paludis/dep_atom.hh b/paludis/dep_atom.hh
index 0b7e4c4..f525436 100644
--- a/paludis/dep_atom.hh
+++ b/paludis/dep_atom.hh
@@ -34,7 +34,7 @@
/** \file
* Declarations for the DepAtom classes.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
namespace paludis
@@ -50,6 +50,8 @@ namespace paludis
/**
* Visitor types for a visitor that can visit a DepAtom heirarchy.
+ *
+ * \ingroup grpdepatoms
*/
typedef VisitorTypes<PackageDepAtom *, PlainTextDepAtom *, AllDepAtom *, AnyDepAtom *,
UseDepAtom *, BlockDepAtom *> DepAtomVisitorTypes;
@@ -57,7 +59,7 @@ namespace paludis
/**
* Base class for a dependency atom.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class DepAtom :
public virtual VisitableInterface<DepAtomVisitorTypes>,
@@ -69,6 +71,9 @@ namespace paludis
DepAtom();
public:
+ /**
+ * Destructor.
+ */
virtual ~DepAtom();
/**
@@ -82,7 +87,7 @@ namespace paludis
* Class for dependency atoms that have a number of child dependency
* atoms.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class CompositeDepAtom :
public DepAtom,
@@ -131,7 +136,7 @@ namespace paludis
/**
* Represents a "|| ( )" dependency block.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class AnyDepAtom :
public CompositeDepAtom,
@@ -148,7 +153,7 @@ namespace paludis
* Represents a ( first second third ) or top level group of dependency
* atoms.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class AllDepAtom :
public CompositeDepAtom,
@@ -164,7 +169,7 @@ namespace paludis
/**
* Represents a use? ( ) dependency atom.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class UseDepAtom :
public CompositeDepAtom,
@@ -202,6 +207,8 @@ namespace paludis
/**
* A StringDepAtom represents a non-composite dep atom with an associated
* piece of text.
+ *
+ * \ingroup grpdepatoms
*/
class StringDepAtom :
public DepAtom
@@ -213,6 +220,9 @@ namespace paludis
StringDepAtom(const std::string &);
public:
+ /**
+ * Fetch our text.
+ */
const std::string & text() const
{
return _str;
@@ -224,7 +234,7 @@ namespace paludis
* 'app-editors/vim'), possibly with associated version and SLOT
* restrictions.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class PackageDepAtom :
public StringDepAtom,
@@ -319,7 +329,7 @@ namespace paludis
* A PlainTextDepAtom represents a plain text entry (for example,
* a URI in SRC_URI).
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class PlainTextDepAtom :
public StringDepAtom,
@@ -335,6 +345,12 @@ namespace paludis
typedef CountedPtr<const PlainTextDepAtom, count_policy::InternalCountTag> ConstPointer;
};
+ /**
+ * Thrown if an invalid package dep atom specification is encountered.
+ *
+ * \ingroup grpexceptions
+ * \ingroup grpdepatoms
+ */
class PackageDepAtomError :
public Exception
{
@@ -344,6 +360,8 @@ namespace paludis
/**
* A PackageDepAtom can be written to an ostream.
+ *
+ * \ingroup grpdepatoms
*/
std::ostream & operator<< (std::ostream &, const PackageDepAtom &);
@@ -352,7 +370,7 @@ namespace paludis
* 'app-editors/vim'), possibly with associated version and SLOT
* restrictions.
*
- * \ingroup DepResolver
+ * \ingroup grpdepatoms
*/
class BlockDepAtom :
public StringDepAtom,
diff --git a/paludis/dep_atom_TEST.cc b/paludis/dep_atom_TEST.cc
index 4cbec37..97d5851 100644
--- a/paludis/dep_atom_TEST.cc
+++ b/paludis/dep_atom_TEST.cc
@@ -21,6 +21,12 @@
#include <test/test_framework.hh>
#include <test/test_runner.hh>
+/** \file
+ * Test cases for dep_atom.hh classes.
+ *
+ * \ingroup grptestcases
+ */
+
using namespace paludis;
using namespace test;
@@ -29,7 +35,7 @@ namespace test_cases
/**
* \test Test DepAtom as_ functions.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepAtomAsTest : TestCase
{
@@ -49,7 +55,7 @@ namespace test_cases
/**
* \test Test DepAtom composite functions.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepAtomCompositeTest : TestCase
{
@@ -73,7 +79,7 @@ namespace test_cases
/**
* \test Test PackageDepAtom.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct PackageDepAtomTest : TestCase
{
diff --git a/paludis/dep_atom_dumper.cc b/paludis/dep_atom_dumper.cc
index 2ca6149..ce845d9 100644
--- a/paludis/dep_atom_dumper.cc
+++ b/paludis/dep_atom_dumper.cc
@@ -21,6 +21,12 @@
#include <paludis/dep_atom.hh>
#include <paludis/dep_atom_dumper.hh>
+/** \file
+ * Implementation for dep_atom_dumper.hh.
+ *
+ * \ingroup grpdepatomdumper
+ */
+
using namespace paludis;
DepAtomDumper::DepAtomDumper(std::ostream * const o) :
diff --git a/paludis/dep_atom_dumper.hh b/paludis/dep_atom_dumper.hh
index f66d523..44f39f0 100644
--- a/paludis/dep_atom_dumper.hh
+++ b/paludis/dep_atom_dumper.hh
@@ -25,12 +25,16 @@
/** \file
* Declarations for the DepAtomDumper class.
+ *
+ * \ingroup grpdepatomdumper
*/
namespace paludis
{
/**
* Dump dependency atoms to a stream in pseudo-XML form, for testing.
+ *
+ * \ingroup grpdepatomdumper
*/
class DepAtomDumper :
public DepAtomVisitorTypes::ConstVisitor,
diff --git a/paludis/dep_atom_dumper_TEST.cc b/paludis/dep_atom_dumper_TEST.cc
index e6ca534..c6bbc1c 100644
--- a/paludis/dep_atom_dumper_TEST.cc
+++ b/paludis/dep_atom_dumper_TEST.cc
@@ -29,7 +29,7 @@ using namespace paludis;
/** \file
* Test cases for DepAtomDumper.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
namespace test_cases
@@ -37,7 +37,7 @@ namespace test_cases
/**
* \test Test DepAtomDumper.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepAtomDumperTest : TestCase
{
@@ -62,3 +62,4 @@ namespace test_cases
}
} test_dep_atom_dumper;
}
+
diff --git a/paludis/dep_atom_flattener.cc b/paludis/dep_atom_flattener.cc
index 054ee59..77c29ae 100644
--- a/paludis/dep_atom_flattener.cc
+++ b/paludis/dep_atom_flattener.cc
@@ -20,6 +20,12 @@
#include <paludis/dep_atom.hh>
#include <paludis/dep_atom_flattener.hh>
+/** \file
+ * Implementation of dep_atom_flattener.hh.
+ *
+ * \ingroup grpdepatomflattener
+ */
+
using namespace paludis;
DepAtomFlattener::DepAtomFlattener(
diff --git a/paludis/dep_atom_flattener.hh b/paludis/dep_atom_flattener.hh
index 6c470ee..9cedee3 100644
--- a/paludis/dep_atom_flattener.hh
+++ b/paludis/dep_atom_flattener.hh
@@ -27,11 +27,22 @@
#include <paludis/util/attributes.hh>
#include <paludis/util/instantiation_policy.hh>
+/**
+ * Declarations for DepAtomFlattener.
+ *
+ * \ingroup grpdepatomflattener
+ */
+
namespace paludis
{
/**
* Extract the enabled components of a dep heirarchy for a particular
* package.
+ *
+ * This is useful for picking out SRC_URI, PROVIDE etc components. It is
+ * <b>not</b> suitable for heirarchies that can contain || ( ) blocks.
+ *
+ * \ingroup grpdepatomflattener
*/
class DepAtomFlattener :
private InstantiationPolicy<DepAtomFlattener, instantiation_method::NonCopyableTag>,
diff --git a/paludis/dep_atom_pretty_printer.cc b/paludis/dep_atom_pretty_printer.cc
index 6ba7409..5de7f4a 100644
--- a/paludis/dep_atom_pretty_printer.cc
+++ b/paludis/dep_atom_pretty_printer.cc
@@ -22,6 +22,12 @@
#include <paludis/dep_atom_pretty_printer.hh>
#include <paludis/util/save.hh>
+/** \file
+ * Implementation of dep_atom_pretty_printer.hh.
+ *
+ * \ingroup grpdepatomprettyprinter
+ */
+
using namespace paludis;
std::ostream &
diff --git a/paludis/dep_atom_pretty_printer.hh b/paludis/dep_atom_pretty_printer.hh
index 1513028..59ac6be 100644
--- a/paludis/dep_atom_pretty_printer.hh
+++ b/paludis/dep_atom_pretty_printer.hh
@@ -24,10 +24,18 @@
#include <paludis/dep_atom.hh>
#include <sstream>
+/** \file
+ * Declarations for the DepAtomPrettyPrinter class.
+ *
+ * \ingroup grpdepatomprettyprinter
+ */
+
namespace paludis
{
/**
- * Pretty print dependency atoms
+ * Pretty print dependency atoms.
+ *
+ * \ingroup grpdepatomprettyprinter
*/
class DepAtomPrettyPrinter :
public DepAtomVisitorTypes::ConstVisitor
@@ -65,6 +73,8 @@ namespace paludis
/**
* Output a DepAtomPrettyPrinter to an ostream.
+ *
+ * \ingroup grpdepatomprettyprinter
*/
std::ostream & operator<< (std::ostream & s, const DepAtomPrettyPrinter & p);
}
diff --git a/paludis/dep_lexer.cc b/paludis/dep_lexer.cc
index 3c1dc0f..2e14ad1 100644
--- a/paludis/dep_lexer.cc
+++ b/paludis/dep_lexer.cc
@@ -23,6 +23,12 @@
#include <paludis/util/tokeniser.hh>
#include <vector>
+/** \file
+ * Implementation of dep_lexer.hh things.
+ *
+ * \ingroup grpdeplexer
+ */
+
using namespace paludis;
DepStringLexError::DepStringLexError(const std::string & dep_string,
@@ -70,3 +76,4 @@ DepLexer::DepLexer(const std::string & s)
_tokens.push_back(std::make_pair(dpl_text, *t));
}
}
+
diff --git a/paludis/dep_lexer.hh b/paludis/dep_lexer.hh
index 397bc47..092a3f9 100644
--- a/paludis/dep_lexer.hh
+++ b/paludis/dep_lexer.hh
@@ -28,8 +28,7 @@
/** \file
* Declarations for the DepLexer class.
*
- * \ingroup DepResolver
- * \ingroup Exception
+ * \ingroup grpdeplexer
*/
namespace paludis
@@ -38,8 +37,8 @@ namespace paludis
* A DepStringError descendent is thrown if an invalid depend string is
* encountered.
*
- * \ingroup Exception
- * \ingroup DepResolver
+ * \ingroup grpdeplexer
+ * \ingroup grpexceptions
*/
class DepStringError : public Exception
{
@@ -55,8 +54,8 @@ namespace paludis
* A DepStringLexError is thrown if a lex-level error is encountered when
* parsing a dependency string.
*
- * \ingroup Exception
- * \ingroup DepResolver
+ * \ingroup grpdeplexer
+ * \ingroup grpexceptions
*/
class DepStringLexError : public DepStringError
{
@@ -70,6 +69,10 @@ namespace paludis
/**
* Lexemes used by DepLexer.
+ *
+ * \see DepLexer
+ *
+ * \ingroup grpdeplexer
*/
enum DepLexerLexeme
{
@@ -82,7 +85,12 @@ namespace paludis
};
/**
- * Converts a dependency string into a sequence of tokens.
+ * Converts a dependency string into a sequence of tokens, which are
+ * then handled by DepParser.
+ *
+ * \see DepParser
+ *
+ * \ingroup grpdeplexer
*/
class DepLexer :
private InstantiationPolicy<DepLexer, instantiation_method::NonCopyableTag>
diff --git a/paludis/dep_lexer_TEST.cc b/paludis/dep_lexer_TEST.cc
index 081ce73..5361e84 100644
--- a/paludis/dep_lexer_TEST.cc
+++ b/paludis/dep_lexer_TEST.cc
@@ -28,7 +28,7 @@ using namespace paludis;
/** \file
* Test cases for DepLexer.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
namespace test_cases
@@ -36,7 +36,7 @@ namespace test_cases
/**
* \test Test DepLexer with an empty input.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerEmptyTest : TestCase
{
@@ -53,7 +53,7 @@ namespace test_cases
/**
* \test Test DepLexer with a blank input.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerBlankTest : TestCase
{
@@ -73,7 +73,7 @@ namespace test_cases
/**
* \test Test DepLexer with a package.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerPackageTest : TestCase
{
@@ -93,7 +93,7 @@ namespace test_cases
/**
* \test Test DepParser with a sequence of packages.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerPackagesTest : TestCase
{
@@ -131,7 +131,7 @@ namespace test_cases
/**
* \test Test DepLexer with an any group.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerAnyTest : TestCase
{
@@ -185,7 +185,7 @@ namespace test_cases
/**
* \test Test DepLexer with a use group.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerUseTest : TestCase
{
@@ -231,7 +231,7 @@ namespace test_cases
/**
* \test Test DepLexer with bad input.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepLexerBadTest : TestCase
{
diff --git a/paludis/dep_parser.cc b/paludis/dep_parser.cc
index 2e96a42..5485dda 100644
--- a/paludis/dep_parser.cc
+++ b/paludis/dep_parser.cc
@@ -24,6 +24,12 @@
#include <paludis/util/stringify.hh>
#include <stack>
+/** \file
+ * Implementation for dep_parser.hh things.
+ *
+ * \ingroup grpdepparser
+ */
+
using namespace paludis;
DepStringParseError::DepStringParseError(const std::string & d,
@@ -37,15 +43,18 @@ DepStringNestingError::DepStringNestingError(const std::string & dep_string) thr
{
}
-enum DepParserState
+namespace
{
- dps_initial,
- dps_had_double_bar,
- dps_had_double_bar_space,
- dps_had_paren,
- dps_had_use_flag,
- dps_had_use_flag_space
-};
+ enum DepParserState
+ {
+ dps_initial,
+ dps_had_double_bar,
+ dps_had_double_bar_space,
+ dps_had_paren,
+ dps_had_use_flag,
+ dps_had_use_flag_space
+ };
+}
CompositeDepAtom::Pointer
DepParser::parse(const std::string & s, const DepParserPolicyInterface * const policy)
diff --git a/paludis/dep_parser.hh b/paludis/dep_parser.hh
index 5c2186e..cf6a213 100644
--- a/paludis/dep_parser.hh
+++ b/paludis/dep_parser.hh
@@ -30,8 +30,7 @@
/** \file
* Declarations for the DepParser class.
*
- * \ingroup DepResolver
- * \ingroup Exception
+ * \ingroup grpdepparser
*/
namespace paludis
@@ -40,8 +39,8 @@ namespace paludis
* A DepStringParseError is thrown if an error is encountered when parsing
* a dependency string.
*
- * \ingroup Exception
- * \ingroup DepResolver
+ * \ingroup grpexceptions
+ * \ingroup grpdepparser
*/
class DepStringParseError : public DepStringError
{
@@ -56,6 +55,9 @@ namespace paludis
/**
* A DepStringNestingError is thrown if a dependency string does not have
* properly balanced parentheses.
+ *
+ * \ingroup grpexceptions
+ * \ingroup grpdepparser
*/
class DepStringNestingError : public DepStringParseError
{
@@ -66,18 +68,40 @@ namespace paludis
DepStringNestingError(const std::string & dep_string) throw ();
};
+ /**
+ * Interface provided by DepParserPolicy classes.
+ *
+ * \see DepParserPolicy
+ *
+ * \ingroup grpdepparser
+ */
struct DepParserPolicyInterface
{
+ /**
+ * Create a new text atom from the provided string.
+ */
virtual CountedPtr<DepAtom> new_text_atom(const std::string &) const = 0;
+ /**
+ * Are || ( ) deps permitted?
+ */
virtual bool permit_any_deps() const = 0;
+ /**
+ * Destructor.
+ */
virtual ~DepParserPolicyInterface()
{
}
-
};
+ /**
+ * Policy class describing how DepParser::parse should behave.
+ *
+ * \see DepParser
+ *
+ * \ingroup grpdepparser
+ */
template <typename TextAtom_, bool permit_any_>
class DepParserPolicy :
public DepParserPolicyInterface,
@@ -104,6 +128,14 @@ namespace paludis
}
};
+ /**
+ * Policy class describing how DepParser::parse should behave
+ * (specialisation for PackageDepAtom).
+ *
+ * \see DepParser
+ *
+ * \ingroup grpdepparser
+ */
template <bool permit_any_>
class DepParserPolicy<PackageDepAtom, permit_any_> :
public DepParserPolicyInterface,
@@ -136,7 +168,10 @@ namespace paludis
/**
* The DepParser converts string representations of a dependency
- * specification into a DepAtom instance.
+ * specification into a DepAtom instance. The DepLexer class is
+ * used as the first stage.
+ *
+ * \ingroup grpdepparser
*/
class DepParser :
private InstantiationPolicy<DepParser, instantiation_method::NonInstantiableTag>
diff --git a/paludis/dep_parser_TEST.cc b/paludis/dep_parser_TEST.cc
index 631f59d..a88e0c4 100644
--- a/paludis/dep_parser_TEST.cc
+++ b/paludis/dep_parser_TEST.cc
@@ -28,7 +28,7 @@ using namespace paludis;
/** \file
* Test cases for DepParser.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
namespace test_cases
@@ -36,7 +36,7 @@ namespace test_cases
/**
* \test Test DepParser with an empty input.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserEmptyTest : TestCase
{
@@ -54,7 +54,7 @@ namespace test_cases
/**
* \test Test DepParser with a blank input.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserBlankTest : TestCase
{
@@ -72,7 +72,7 @@ namespace test_cases
/**
* \test Test DepParser with a package.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserPackageTest : TestCase
{
@@ -90,7 +90,7 @@ namespace test_cases
/**
* \test Test DepParser with a decorated package.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserDecoratedPackageTest : TestCase
{
@@ -121,7 +121,7 @@ namespace test_cases
/**
* \test Test DepParser with a sequence of packages.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserPackagesTest : TestCase
{
@@ -140,7 +140,7 @@ namespace test_cases
/**
* \test Test DepParser with an any group.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserAnyTest : TestCase
{
@@ -159,7 +159,7 @@ namespace test_cases
/**
* \test Test DepParser with an all group.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserAllTest : TestCase
{
@@ -178,7 +178,7 @@ namespace test_cases
/**
* \test Test DepParser with a use group.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserUseTest : TestCase
{
@@ -197,7 +197,7 @@ namespace test_cases
/**
* \test Test DepParser with an inverse use group.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserInvUseTest : TestCase
{
@@ -216,7 +216,7 @@ namespace test_cases
/**
* \test Test DepParser nesting errors.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserBadNestingTest : TestCase
{
@@ -237,7 +237,7 @@ namespace test_cases
/**
* \test Test DepParser weird errors.
*
- * \ingroup Test
+ * \ingroup grptestcases
*/
struct DepParserBadValuesTest : TestCase
{
diff --git a/paludis/dep_tag.cc b/paludis/dep_tag.cc
index 0a97386..67be095 100644
--- a/paludis/dep_tag.cc
+++ b/paludis/dep_tag.cc
@@ -19,10 +19,23 @@
#include "dep_tag.hh"
+/** \file
+ * Implementation for DepTag, DepTagCategory etc.
+ *
+ * \ingroup grpdeptag
+ */
+
using namespace paludis;
namespace
{
+ /**
+ * Create the DepTagCategory for GLSAs.
+ *
+ * \see register_glsa_dep_tag
+ *
+ * \ingroup grpdeptag
+ */
DepTagCategory::ConstPointer
make_glsa_dep_tag()
{
@@ -32,9 +45,15 @@ namespace
"Your system is potentially affected by these security issues:",
"Please read the advisories carefully and take appropriate action."));
}
+
+ /**
+ * Register the GLSA dep tag category instance.
+ *
+ * \ingroup grpdeptag
+ */
+ static const DepTagCategoryMaker::RegisterMaker register_glsa_dep_tag("glsa",
+ &make_glsa_dep_tag);
}
-static const DepTagCategoryMaker::RegisterMaker register_glsa_dep_tag("glsa",
- &make_glsa_dep_tag);
DepTagCategory::DepTagCategory(const std::string & id,
const std::string & t, const std::string & pre,
diff --git a/paludis/dep_tag.hh b/paludis/dep_tag.hh
index 6d6da91..5f98cb85 100644
--- a/paludis/dep_tag.hh
+++ b/paludis/dep_tag.hh
@@ -20,6 +20,12 @@
#ifndef PALUDIS_GUARD_PALUDIS_DEP_TAG_HH
#define PALUDIS_GUARD_PALUDIS_DEP_TAG_HH 1
+/** \file
+ * Declarations for the DepTag and DepTagCategory classes.
+ *
+ * \ingroup grpdeptag
+ */
+
#include <string>
#include <paludis/util/instantiation_policy.hh>
#include <paludis/util/visitor.hh>
@@ -29,6 +35,17 @@
namespace paludis
{
+ /**
+ * A DepTagCategory is identified by its name and has associated display
+ * information for a DepTag's category.
+ *
+ * It is usually accessed via DepTagCategoryMaker.
+ *
+ * \see DepTagCategoryMaker
+ * \see DepTag
+ *
+ * \ingroup grpdeptag
+ */
class DepTagCategory :
InstantiationPolicy<DepTagCategory, instantiation_method::NonCopyableTag>,
public InternalCounted<DepTagCategory>
@@ -40,32 +57,54 @@ namespace paludis
const std::string _post_text;
public:
+ /**
+ * Constructor.
+ */
DepTagCategory(const std::string & id,
const std::string & t,
const std::string & pre,
const std::string & post);
+ /**
+ * Fetch our short ID (for example, 'GLSA').
+ */
std::string id() const
{
return _id;
}
+ /**
+ * Fetch our title (for example, 'Security advisories'), or an
+ * empty string if we're untitled.
+ */
std::string title() const
{
return _title;
}
+ /**
+ * Fetch our pre list text, or an empty string.
+ */
std::string pre_text() const
{
return _pre_text;
}
+ /**
+ * Fetch our post list text, or an empty string.
+ */
std::string post_text() const
{
return _post_text;
}
};
+ /**
+ * Thrown if DepTagCategoryMaker cannot find the named DepTagCategory.
+ *
+ * \ingroup grpexceptions
+ * \ingroup grpdeptag
+ */
class NoSuchDepTagCategory :
public Exception
{
@@ -73,31 +112,70 @@ namespace paludis
NoSuchDepTagCategory(const std::string &) throw ();
};
+ /**
+ * Virtual constructor for accessing DepTagCategory instances.
+ *
+ * \ingroup grpdeptag
+ */
typedef VirtualConstructor<std::string, DepTagCategory::ConstPointer (*) (),
virtual_constructor_not_found::ThrowException<NoSuchDepTagCategory> > DepTagCategoryMaker;
class DepTag;
class GLSADepTag;
+ /**
+ * Visitor class for visiting the different DepTag subclasses.
+ *
+ * \ingroup grpdeptag
+ */
typedef VisitorTypes<GLSADepTag *> DepTagVisitorTypes;
+ /**
+ * A DepTag can be associated with a PackageDepAtom, and is transferred
+ * onto any associated DepListEntry instances.
+ *
+ * It is used for tagging dep list entries visually, for example to
+ * indicate an associated GLSA.
+ *
+ * \ingroup grpdeptag
+ */
class DepTag :
InstantiationPolicy<DepTag, instantiation_method::NonCopyableTag>,
public InternalCounted<DepTag>,
public virtual VisitableInterface<DepTagVisitorTypes>
{
protected:
+ /**
+ * Constructor.
+ */
DepTag();
public:
+ /**
+ * Destructor.
+ */
virtual ~DepTag();
+ /**
+ * Fetch our short text (for example, 'GLSA-1234') that is
+ * displayed with the dep list entry.
+ */
virtual std::string short_text() const = 0;
+ /**
+ * Fetch our DepTagCategory's tag.
+ */
virtual std::string category() const = 0;
+ /**
+ * Used for comparisons in containers containing pointers to DepTag
+ * instances.
+ *
+ * \ingroup grpdeptag
+ */
struct Comparator
{
+ /// Perform the comparison.
bool operator() (const DepTag::ConstPointer & d1,
const DepTag::ConstPointer & d2) const
{
@@ -106,6 +184,11 @@ namespace paludis
};
};
+ /**
+ * DepTag subclass for GLSAs.
+ *
+ * \ingroup grpdeptag
+ */
class GLSADepTag :
public DepTag,
public Visitable<GLSADepTag, DepTagVisitorTypes>
@@ -115,12 +198,19 @@ namespace paludis
const std::string _glsa_title;
public:
+ /**
+ * Constructor.
+ */
GLSADepTag(const std::string & id, const std::string & glsa_title);
virtual std::string short_text() const;
virtual std::string category() const;
+ /**
+ * Fetch our GLSA title (for example, 'Yet another PHP remote access
+ * hole').
+ */
std::string glsa_title() const;
};
}