aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-01-29 10:55:22 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-01-29 10:55:22 +0000
commit60530c6b6a066814ba4d8cc46df11bc731a2faad (patch)
tree16508c80f2a5e98be9925f9ed0955a7ce1e9a86c
parentba5801299006895b21384599c6197782cb084b2d (diff)
downloadpaludis-60530c6b6a066814ba4d8cc46df11bc731a2faad.tar.gz
paludis-60530c6b6a066814ba4d8cc46df11bc731a2faad.tar.xz
Docs updates
-rw-r--r--doc/Makefile.am3
-rw-r--r--doc/doc_coding_standards.doxygen200
-rw-r--r--doc/doc_main.doxygen336
-rw-r--r--doc/doc_mainpage.doxygen56
-rw-r--r--doc/doc_references.doxygen32
-rw-r--r--paludis/container_entry.hh5
-rw-r--r--paludis/pstream.hh5
-rw-r--r--paludis/save.hh3
8 files changed, 391 insertions, 249 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index a89798e..482c840 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -6,7 +6,8 @@ docfiles = \
doc_mainpage.doxygen \
doc_coding_standards.doxygen \
doc_namespaces.doxygen \
- doc_directories.doxygen
+ doc_directories.doxygen \
+ doc_references.doxygen
EXTRA_DIST = doxygen.conf.in $(docfiles)
diff --git a/doc/doc_coding_standards.doxygen b/doc/doc_coding_standards.doxygen
index 3892923..944a9cb 100644
--- a/doc/doc_coding_standards.doxygen
+++ b/doc/doc_coding_standards.doxygen
@@ -1,21 +1,23 @@
/* vim: set ft=cpp tw=80 sw=4 et : */
-/** \page CodingStandards Coding Standards
- *
- * These are rough guidelines. You should stick to these unless there's a good
- * reason to do otherwise. There are lots more standards that aren't documented
- * here yet -- ask for clarification as necessary.
- *
- * \section CodingStandardsIndentingAndSpacing Indenting and Spacing
- *
- * Indents are four spaces. There are no tabs anywhere. Braces go on a line of
- * their own, and may be omitted if the clarity of the code isn't affected.
- *
- * Function calls have no space before or after the parentheses. Most operators
- * and built-in functions have spaces before the opening parenthesis but not
- * inside.
- *
- * For example::
+/**
+\page CodingStandards Coding Standards
+
+These are rough guidelines. You should stick to these unless there's a good
+reason to do otherwise. There are lots more standards that aren't documented
+here yet -- ask for clarification as necessary.
+
+\section CodingStandardsIndentingAndSpacing Indenting and Spacing
+
+Indents are four spaces. There are no tabs anywhere. Braces go on a line of
+their own, and may be omitted if the clarity of the code isn't affected. Make
+sure you don't include trailing whitespace.
+
+Function calls have no space before or after the parentheses. Most operators
+and built-in functions have spaces before the opening parenthesis but not
+inside.
+
+For example::
\code
if (some_function("moo", 2))
do_stuff("moo");
@@ -26,33 +28,139 @@ else
++foo;
}
\endcode
- *
- * \section CodingStandardsNaming Naming
- *
- * Types are named in MixedCaseNoUnderscores.
- *
- * Variables and functions are named in lower_case_with_underscores.
- *
- * Private member variables that aren't going to end up being used anywhere
- * external are _prefixed_with_underscore.
- *
- * Template values are suffixed_with_underscore_, and template typenames are
- * SuffixedAsWell_ (and use typename rather than class).
- *
- * The files for SomeClass (and any small related utilities) would be
- * some_class.hh and some_class.cc .
- *
- * Macros are PALUDIS_UPPER_CASE, but they're evil so don't use them.
- *
- * \section CodingStandardsNamespaces Namespaces
- *
- * Everything under paludis/ should be inside namespace paludis. Sometimes
- * sub-namespaces are used where they look useful.
- *
- * Never use using namespace std.
- *
- * \section CodingStandardsIncludeGuards Include Guards
- *
- * Include guards are \#define PALUDIS_GUARD_FILE_NAME_HH 1 .
- *
- */
+
+\section CodingStandardsSwitches Switches
+
+You'll sometimes see code like this:
+
+\code
+do
+{
+ switch (my_enum)
+ {
+ case e_one:
+ // ...
+ continue;
+
+ case e_two:
+ // ...
+ continue;
+ }
+
+ throw InternalError(PALUDIS_HERE, "Unexpected value for my_enum");
+} while (false);
+\endcode
+
+The reason for using this rather than a <code>default:</code> label is that the
+compiler will (or at least the compiler we use will) generate a warning if
+someone later goes and adds <code>e_three</code>, and we haven't updated our
+switch to recognise it.
+
+\section CodingStandardsComments Comments
+
+All public and protected interfaces and classes should be documented in the
+header files via Doxygen. Implementations should be documented appropriately --
+explain complicated or unobvious parts and anything that can easily be broken
+by other people. Don't bother with comments on obvious things.
+
+\section CodingStandardsNaming Naming
+
+Types are named in <code>MixedCaseNoUnderscores</code>.
+
+Variables and functions are named in <code>lower_case_with_underscores</code>.
+
+Private member variables that aren't going to end up being used anywhere
+external are <code>_prefixed_with_underscore</code>.
+
+Template values are <code>suffixed_with_underscore_</code>, and template
+typenames are <code>SuffixedAsWell_</code> (and use <code>typename</code> rather
+than <code>class</code>).
+
+The files for <code>SomeClass</code> (and any small related utilities) would be
+<code>some_class.hh</code> and <code>some_class.cc</code>. We are somewhat
+inconsistent when it comes to what warrants its own file -- originally it was
+pretty much one class per file, but then compiles started taking too long so
+it's now more like one class plus related utilities and exceptions per file.
+
+Macros are <code>PALUDIS_UPPER_CASE</code>, but they're evil (\ref TCppPL
+section 7.8, \ref EffCpp item 2) so don't use them.
+
+Very short names for loop indices and the like are fine, but prefer longer,
+self-documenting names for proper variables. For loop iterator pairs, the
+usual style is:
+
+\code
+for (MyType::Iterator i(my_container.begin()), i_end(my_container.end()) ;
+ i != i_end ; ++i)
+{
+ // ...
+}
+\endcode
+
+If there's a convenient standard library algorithm available, use that
+instead of a manual loop (\ref EffSTL item 43).
+
+\section CodingStandardsPointers Pointers and References
+
+Try to avoid returning raw pointer types from raw interfaces, especially if the
+programmer is expected to deallocate them manually. Make liberal use of
+<code>paludis::CountedPtr</code> instead -- it's low overhead and a lot less
+prone to subtle screwups. See \ref EffCpp item 18.
+
+Pass object parameters by const reference rather than pointer to const unless
+you're prepared to accept a zero pointer. Avoid pass by value except for small
+integral types. See \ref EffCpp item 20.
+
+\section CodingStandardsNamespaces Namespaces
+
+Everything under <code>paludis/</code> should be inside namespace
+<code>paludis</code>. Sometimes sub-namespaces are used where they look useful.
+
+\section CodingStandardsIncludeGuards Include Guards
+
+Include guards are <code>\#define PALUDIS_GUARD_FILE_NAME_HH 1</code>.
+
+\section CodingStandardsStandardLibrary Standard Library
+
+Never use <code>using namespace std</code>. It can bring arbitrary weirdness
+into the current namespace. It's ok to selectively introduce things from std
+where they're used a lot. See \ref TCppPL section 8.2.9.1.
+
+Make use of the standard library where suitable. It has fewer bugs than
+code you write yourself, and it may be doing clever optimisations behind
+the scenes.
+
+Remember the container member functions. Many containers have template
+constructors that take iterator pairs. Many containers have assign and
+swap methods. Use these over <code>std::copy</code>. See \ref EffSTL item
+25.
+
+Don't use <code>vector&lt;bool&gt;</code>. It's just not worth it. See
+\ref EffSTL item 18.
+
+Although some compilers will let you get away with <code>std::make_pair("foo",
+"bar")</code>, some won't. Strictly speaking this violates the standard.
+Use <code>std::make_pair(std::string("foo"), std::string("bar"))</code> instead.
+
+\section CodingStandardsCasts Casts
+
+<code>dynamic_cast</code> is banned. It's slow (\ref EffCpp item 27) and a sign
+that you should be using one of visitors (\ref GoF Visitor), multiple dispatch
+(\ref MCppD chapter 11) or capability queries via a <code>get_interface</code>
+type method (for example, as described in \ref GoF Composite -- Implementation
+item 4) instead.
+
+<code>reinterpret_cast</code> is probably banned as well, unless we end up
+having to talk to some weirdly broken C libraries.
+
+There are very few legitimate uses for <code>const_cast</code>. It
+<em>might</em> be ok to use it as described in \ref EffCpp item 3. It
+<em>might</em> be ok to use it to talk to C libraries.
+
+There's nothing wrong with making appropriate use of <code>static_cast</code>.
+
+Old C style <code>(Type) variable</code> casts are banned. Function style casts
+(that is, <code>Type(value)</code>) should only be used when calling an explicit
+constructor to pass an object to a function. See \ref EffCpp item 27.
+
+*/
diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index c39267a..2e23fe2 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -1,201 +1,201 @@
/* vim: set ft=cpp tw=80 sw=4 et : */
/** \defgroup DepResolver Dependency parsing and resolution
- * Dependency parsing and resolution.
- *
- * Dependency resolution is handled in stages. We convert a dependency string
- * into a tree structure, and then define a visitor over this structure.
- *
- * \section DepResolverImportant Important Classes
- *
- * - paludis::DepList creates and holds dependency lists
- * - paludis::DepParser turns a dependency string into a paludis::DepAtom
- * heirarchy.
- */
+Dependency parsing and resolution.
+
+Dependency resolution is handled in stages. We convert a dependency string
+into a tree structure, and then define a visitor over this structure.
+
+\section DepResolverImportant Important Classes
+
+- paludis::DepList creates and holds dependency lists
+- paludis::DepParser turns a dependency string into a paludis::DepAtom
+ heirarchy.
+*/
/** \defgroup Environment Environment
- * Environment.
- *
- * These classes represent the environment in which paludis is running.
- *
- * \section EnvironmentImportant Important Classes
- *
- * - 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).
- */
+Environment.
+
+These classes represent the environment in which paludis is running.
+
+\section EnvironmentImportant Important Classes
+
+- 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 Database Package database functionality
- * Package database functionality.
- *
- * These classes provide checked representations for common data types, as
- * well as the core queryable package database functionality.
- *
- * \section DatabaseImportant Important Classes
- *
- * - paludis::PackageDatabase represents a package database, which
- * is queryable and holds zero or more paludis::Repository instances.
- *
- * \ingroup Environment
- */
+Package database functionality.
+
+These classes provide checked representations for common data types, as
+well as the core queryable package database functionality.
+
+\section DatabaseImportant Important Classes
+
+- paludis::PackageDatabase represents a package database, which
+ is queryable and holds zero or more paludis::Repository instances.
+
+\ingroup Environment
+*/
/** \defgroup Utility Utilities
- * Utilities.
- *
- * Various miscellaneous utilities.
- */
+Utilities.
+
+Various miscellaneous utilities.
+*/
/** \defgroup Exception Exception handling
- * Exception handling.
- *
- * 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.
- *
- * \section ExceptionImportant Important classes
- *
- * - 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).
- *
- * \ingroup Utility
- */
+Exception handling.
+
+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.
+
+\section ExceptionImportant Important classes
+
+- 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).
+
+\ingroup Utility
+*/
/** \defgroup Args Command line argument handling
- * Command line handling for a program.
- *
- * 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.
- *
- * \ingroup Utility
- */
+Command line handling for a program.
+
+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.
+
+\ingroup Utility
+*/
/** \defgroup Pointer Pointers
- * Pointers.
- *
- * We use shared pointers in various places. Different policies are available
- * for different reference count models.
- *
- * \section PointerImportant Important Classes
- *
- * - paludis::CountedPtr is used for reference counted pointers.
- *
- * \ingroup Utility
- */
+Pointers.
+
+We use shared pointers in various places. Different policies are available
+for different reference count models.
+
+\section PointerImportant Important Classes
+
+- 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
- */
+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
- */
+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
- */
+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
- */
+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 the GoF book for how visitors work. See the test cases for how to use
- * it.
- *
- * \ingroup Utility
- */
+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 the GoF book for how virtual constructors (called "Factory Methods" in
- * GoF) work. See the test cases for how to use it.
- *
- * \ingroup Utility
- */
+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.
- */
+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.
- */
+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.
+*/
diff --git a/doc/doc_mainpage.doxygen b/doc/doc_mainpage.doxygen
index b098d77..353f60c 100644
--- a/doc/doc_mainpage.doxygen
+++ b/doc/doc_mainpage.doxygen
@@ -1,31 +1,31 @@
/* vim: set ft=cpp tw=80 sw=4 et : */
/** \mainpage
- *
- * \section developerdocs For Developers
- *
- * It's best to start by skimming over the main program to get a feel for how
- * everything fits together. Useful files:
- *
- * - src/paludis.cc The main program.
- * - src/query.cc The --query action handler.
- * - src/install.cc The --install action handler.
- *
- * After that, the following classes are good places to begin:
- *
- * - paludis::DefaultEnvironment provides a representation of the default
- * operating environment.
- * - paludis::PackageDatabase provides routines for querying packages. An
- * instance can be obtained via paludis::DefaultEnvironment.
- *
- * The <a href="modules.html">Modules</a> link in the header bar will probably
- * be of more use than any of the full class lists.
- *
- * You should also read \link CodingStandards the Coding Standards \endlink
- * before tinkering.
- *
- * \section userdocs For End Users
- *
- * You shouldn't be touching paludis at the moment. Go away.
- *
- */
+
+\section developerdocs For Developers
+
+It's best to start by skimming over the main program to get a feel for how
+everything fits together. Useful files:
+
+- src/paludis.cc The main program.
+- src/query.cc The --query action handler.
+- src/install.cc The --install action handler.
+
+After that, the following classes are good places to begin:
+
+- paludis::DefaultEnvironment provides a representation of the default
+ operating environment.
+- paludis::PackageDatabase provides routines for querying packages. An
+ instance can be obtained via paludis::DefaultEnvironment.
+
+The <a href="modules.html">Modules</a> link in the header bar will probably
+be of more use than any of the full class lists.
+
+You should also read \link CodingStandards the Coding Standards \endlink
+before tinkering.
+
+\section userdocs For End Users
+
+You shouldn't be touching paludis at the moment. Go away.
+
+*/
diff --git a/doc/doc_references.doxygen b/doc/doc_references.doxygen
new file mode 100644
index 0000000..553af18
--- /dev/null
+++ b/doc/doc_references.doxygen
@@ -0,0 +1,32 @@
+/* vim: set ft=cpp tw=80 sw=4 et : */
+
+/**
+\page References References
+
+\paragraph EffCpp [EffC++]
+<strong>[EffC++]</strong> Effective C++ Third Edition / Scott Meyer /
+Addison-Wesley / ISBN 0-321-33487-6
+
+\paragraph EffSTL [EffSTL]
+<strong>[EffSTL]</strong> Effective STL / Scott Meyers / Addison-Wesley / ISBN
+0-201-74962-9
+
+\paragraph GoF [GoF]
+<strong>[GoF]</strong> Design Patterns: Elements of Reusable Object-Oriented
+Software / Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides /
+Addison-Wesley / ISBN 0-201-63361-2
+
+\paragraph MCppD [MCppD]
+<strong>[MCppD]</strong> Modern C++ Design: Generic Programming and Design
+Patterns Applied / Andrei Alexandrescu / Addison-Wesley / ISBN 0-201-70431-5
+
+\paragraph TCppSL [TC++SL]
+<strong>[TC++SL]</strong> The C++ Standard Library / Nicolai M. Josuttis /
+Addison-Wesley / ISBN 0-201-37926-0
+
+\paragraph TCppPL [TC++PL]
+<strong>[TC++PL]</strong> The C++ Programming Language Third Edition / Bjarne
+Stroustrup / Addison-Wesley / ISBN 0-201-88954-4
+
+*/
+
diff --git a/paludis/container_entry.hh b/paludis/container_entry.hh
index bbab402..9533e51 100644
--- a/paludis/container_entry.hh
+++ b/paludis/container_entry.hh
@@ -26,14 +26,15 @@ namespace paludis
{
/**
* Hold an entry in a container for as long as our ContainerEntry instance
- * is in scope (RAII).
+ * is in scope (RAII, see \ref EffCpp item 13 or \ref TCppPL section 14.4).
*/
template <typename Container_>
struct ContainerEntry;
/**
* Hold an entry in a container for as long as our ContainerEntry instance
- * is in scope (RAII, partial specialisation for std::list).
+ * is in scope (RAII, see \ref EffCpp item 13 or \ref TCppPL section 14.4;
+ * partial specialisation for std::list).
*/
template <typename Item_>
class ContainerEntry<std::list<Item_> >
diff --git a/paludis/pstream.hh b/paludis/pstream.hh
index 47f49e5..a48ea5f 100644
--- a/paludis/pstream.hh
+++ b/paludis/pstream.hh
@@ -60,9 +60,8 @@ namespace paludis
* Bidirectional I/O isn't supported since we haven't needed it yet, and
* because popen on Linux is unidirectional.
*
- * See Josuttis' "The C++ Standard Library" Ch. 13.13 for what we're doing
- * here. The buffer code is based upon the "io/inbuf1.hpp" example in
- * section 13.13.3.
+ * See \ref TCppSL Ch. 13.13 for what we're doing here. The buffer code is
+ * based upon the "io/inbuf1.hpp" example in section 13.13.3.
*
* \ingroup PStream
*/
diff --git a/paludis/save.hh b/paludis/save.hh
index 9734813..54c1759 100644
--- a/paludis/save.hh
+++ b/paludis/save.hh
@@ -32,7 +32,8 @@ namespace paludis
{
/**
* Save the value of a particular variable and assign it a new value for the
- * duration of the Save instance's lifetime (RAII).
+ * duration of the Save instance's lifetime (RAII, see \ref EffCpp item 13 or
+ * \ref TCppPL section 14.4).
*
* \ingroup Utility
*/