lemon: comparison lemon/adaptors.h

equal deleted inserted replaced

-:63d50c66d347
+:5ebc3a7c4ce4
 #ifndef LEMON_ADAPTORS_H
 #define LEMON_ADAPTORS_H
 /// \ingroup graph_adaptors
 /// \file
-/// \brief Several graph adaptors
+/// \brief Adaptor classes for digraphs and graphs
 ///
 /// This file contains several useful adaptors for digraphs and graphs.
 #include <lemon/core.h>
 #include <lemon/maps.h>
 };
 /// \ingroup graph_adaptors
 ///
-/// \brief A digraph adaptor which reverses the orientation of the arcs.
+/// \brief Adaptor class for reversing the orientation of the arcs in
-///
+/// a digraph.
-/// ReverseDigraph reverses the arcs in the adapted digraph. The
+///
-/// SubDigraph is conform to the \ref concepts::Digraph
+/// ReverseDigraph can be used for reversing the arcs in a digraph.
-/// "Digraph concept".
+/// It conforms to the \ref concepts::Digraph "Digraph" concept.
 ///
-/// \tparam _Digraph It must be conform to the \ref concepts::Digraph
+/// The adapted digraph can also be modified through this adaptor
-/// "Digraph concept". The type can be specified to be const.
+/// by adding or removing nodes or arcs, unless the \c _Digraph template
+/// parameter is set to be \c const.
+///
+/// \tparam _Digraph The type of the adapted digraph.
+/// It must conform to the \ref concepts::Digraph "Digraph" concept.
+/// It can also be specified to be \c const.
+///
+/// \note The \c Node and \c Arc types of this adaptor and the adapted
+/// digraph are convertible to each other.
 template<typename _Digraph>
 class ReverseDigraph :
 public DigraphAdaptorExtender<ReverseDigraphBase<_Digraph> > {
 public:
 typedef _Digraph Digraph;
 ReverseDigraph() { }
 public:
 /// \brief Constructor
 ///
-/// Creates a reverse digraph adaptor for the given digraph
+/// Creates a reverse digraph adaptor for the given digraph.
 explicit ReverseDigraph(Digraph& digraph) {
 Parent::setDigraph(digraph);
 }
 };
-/// \brief Just gives back a reverse digraph adaptor
+/// \brief Returns a read-only ReverseDigraph adaptor
 ///
-/// Just gives back a reverse digraph adaptor
+/// This function just returns a read-only \ref ReverseDigraph adaptor.
+/// \ingroup graph_adaptors
+/// \relates ReverseDigraph
 template<typename Digraph>
 ReverseDigraph<const Digraph> reverseDigraph(const Digraph& digraph) {
 return ReverseDigraph<const Digraph>(digraph);
 }
 template <typename _Digraph, typename _NodeFilterMap,
 typename _ArcFilterMap, bool _checked = true>
 class SubDigraphBase : public DigraphAdaptorBase<_Digraph> {
 public:
 };
 /// \ingroup graph_adaptors
 ///
-/// \brief An adaptor for hiding nodes and arcs in a digraph
+/// \brief Adaptor class for hiding nodes and arcs in a digraph
 ///
-/// SubDigraph hides nodes and arcs in a digraph. A bool node map
+/// SubDigraph can be used for hiding nodes and arcs in a digraph.
-/// and a bool arc map must be specified, which define the filters
+/// A \c bool node map and a \c bool arc map must be specified, which
-/// for nodes and arcs. Just the nodes and arcs with true value are
+/// define the filters for nodes and arcs.
-/// shown in the subdigraph. The SubDigraph is conform to the \ref
+/// Only the nodes and arcs with \c true filter value are
-/// concepts::Digraph "Digraph concept". If the \c _checked parameter
+/// shown in the subdigraph. This adaptor conforms to the \ref
-/// is true, then the arcs incident to filtered nodes are also
+/// concepts::Digraph "Digraph" concept. If the \c _checked parameter
+/// is \c true, then the arcs incident to hidden nodes are also
 /// filtered out.
 ///
-/// \tparam _Digraph It must be conform to the \ref
+/// The adapted digraph can also be modified through this adaptor
-/// concepts::Digraph "Digraph concept". The type can be specified
+/// by adding or removing nodes or arcs, unless the \c _Digraph template
-/// to const.
+/// parameter is set to be \c const.
-/// \tparam _NodeFilterMap A bool valued node map of the the adapted digraph.
+///
-/// \tparam _ArcFilterMap A bool valued arc map of the the adapted digraph.
+/// \tparam _Digraph The type of the adapted digraph.
-/// \tparam _checked If the parameter is false then the arc filtering
+/// It must conform to the \ref concepts::Digraph "Digraph" concept.
-/// is not checked with respect to node filter. Otherwise, each arc
+/// It can also be specified to be \c const.
-/// is automatically filtered, which is incident to a filtered node.
+/// \tparam _NodeFilterMap A \c bool (or convertible) node map of the
+/// adapted digraph. The default map type is
+/// \ref concepts::Digraph::NodeMap "_Digraph::NodeMap<bool>".
+/// \tparam _ArcFilterMap A \c bool (or convertible) arc map of the
+/// adapted digraph. The default map type is
+/// \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<bool>".
+/// \tparam _checked If this parameter is set to \c false, then the arc
+/// filtering is not checked with respect to the node filter.
+/// Otherwise, each arc that is incident to a hidden node is automatically
+/// filtered out. This is the default option.
+///
+/// \note The \c Node and \c Arc types of this adaptor and the adapted
+/// digraph are convertible to each other.
 ///
 /// \see FilterNodes
 /// \see FilterArcs
+#ifdef DOXYGEN
+template<typename _Digraph,
+typename _NodeFilterMap,
+typename _ArcFilterMap,
+bool _checked>
+#else
 template<typename _Digraph,
 typename _NodeFilterMap = typename _Digraph::template NodeMap<bool>,
 typename _ArcFilterMap = typename _Digraph::template ArcMap<bool>,
 bool _checked = true>
+#endif
 class SubDigraph
 : public DigraphAdaptorExtender<
 SubDigraphBase<_Digraph, _NodeFilterMap, _ArcFilterMap, _checked> > {
 public:
+/// The type of the adapted digraph.
 typedef _Digraph Digraph;
+/// The type of the node filter map.
 typedef _NodeFilterMap NodeFilterMap;
+/// The type of the arc filter map.
 typedef _ArcFilterMap ArcFilterMap;
 typedef DigraphAdaptorExtender<
-SubDigraphBase<Digraph, NodeFilterMap, ArcFilterMap, _checked> >
+SubDigraphBase<_Digraph, _NodeFilterMap, _ArcFilterMap, _checked> >
 Parent;
 typedef typename Parent::Node Node;
 typedef typename Parent::Arc Arc;
 SubDigraph() { }
 public:
 /// \brief Constructor
 ///
-/// Creates a subdigraph for the given digraph with
+/// Creates a subdigraph for the given digraph with the
-/// given node and arc map filters.
+/// given node and arc filter maps.
 SubDigraph(Digraph& digraph, NodeFilterMap& node_filter,
 ArcFilterMap& arc_filter) {
 setDigraph(digraph);
 setNodeFilterMap(node_filter);
 setArcFilterMap(arc_filter);
 }
-/// \brief Hides the node of the graph
+/// \brief Hides the given node
 ///
-/// This function hides \c n in the digraph, i.e. the iteration
+/// This function hides the given node in the subdigraph,
-/// jumps over it. This is done by simply setting the value of \c n
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding node-map.
+/// It is done by simply setting the assigned value of \c n
+/// to be \c false in the node filter map.
 void hide(const Node& n) const { Parent::hide(n); }
-/// \brief Hides the arc of the graph
+/// \brief Hides the given arc
 ///
-/// This function hides \c a in the digraph, i.e. the iteration
+/// This function hides the given arc in the subdigraph,
-/// jumps over it. This is done by simply setting the value of \c a
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding arc-map.
+/// It is done by simply setting the assigned value of \c a
+/// to be \c false in the arc filter map.
 void hide(const Arc& a) const { Parent::hide(a); }
-/// \brief Unhides the node of the graph
+/// \brief Shows the given node
 ///
-/// The value of \c n is set to be true in the node-map which stores
+/// This function shows the given node in the subdigraph.
-/// hide information. If \c n was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c n
-/// again
+/// to be \c true in the node filter map.
 void unHide(const Node& n) const { Parent::unHide(n); }
-/// \brief Unhides the arc of the graph
+/// \brief Shows the given arc
 ///
-/// The value of \c a is set to be true in the arc-map which stores
+/// This function shows the given arc in the subdigraph.
-/// hide information. If \c a was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c a
-/// again
+/// to be \c true in the arc filter map.
 void unHide(const Arc& a) const { Parent::unHide(a); }
-/// \brief Returns true if \c n is hidden.
+/// \brief Returns \c true if the given node is hidden.
 ///
-/// Returns true if \c n is hidden.
+/// This function returns \c true if the given node is hidden.
-///
 bool hidden(const Node& n) const { return Parent::hidden(n); }
-/// \brief Returns true if \c a is hidden.
+/// \brief Returns \c true if the given arc is hidden.
 ///
-/// Returns true if \c a is hidden.
+/// This function returns \c true if the given arc is hidden.
-///
 bool hidden(const Arc& a) const { return Parent::hidden(a); }
 };
-/// \brief Just gives back a subdigraph
+/// \brief Returns a read-only SubDigraph adaptor
 ///
-/// Just gives back a subdigraph
+/// This function just returns a read-only \ref SubDigraph adaptor.
+/// \ingroup graph_adaptors
+/// \relates SubDigraph
 template<typename Digraph, typename NodeFilterMap, typename ArcFilterMap>
 SubDigraph<const Digraph, NodeFilterMap, ArcFilterMap>
 subDigraph(const Digraph& digraph, NodeFilterMap& nfm, ArcFilterMap& afm) {
 return SubDigraph<const Digraph, NodeFilterMap, ArcFilterMap>
 (digraph, nfm, afm);
 };
 /// \ingroup graph_adaptors
 ///
-/// \brief A graph adaptor for hiding nodes and edges in an
+/// \brief Adaptor class for hiding nodes and edges in an undirected
-/// undirected graph.
+/// graph.
 ///
-/// SubGraph hides nodes and edges in a graph. A bool node map and a
+/// SubGraph can be used for hiding nodes and edges in a graph.
-/// bool edge map must be specified, which define the filters for
+/// A \c bool node map and a \c bool edge map must be specified, which
-/// nodes and edges. Just the nodes and edges with true value are
+/// define the filters for nodes and edges.
-/// shown in the subgraph. The SubGraph is conform to the \ref
+/// Only the nodes and edges with \c true filter value are
-/// concepts::Graph "Graph concept". If the \c _checked parameter is
+/// shown in the subgraph. This adaptor conforms to the \ref
-/// true, then the edges incident to filtered nodes are also
+/// concepts::Graph "Graph" concept. If the \c _checked parameter is
+/// \c true, then the edges incident to hidden nodes are also
 /// filtered out.
 ///
-/// \tparam _Graph It must be conform to the \ref
+/// The adapted graph can also be modified through this adaptor
-/// concepts::Graph "Graph concept". The type can be specified
+/// by adding or removing nodes or edges, unless the \c _Graph template
-/// to const.
+/// parameter is set to be \c const.
-/// \tparam _NodeFilterMap A bool valued node map of the the adapted graph.
+///
-/// \tparam _EdgeFilterMap A bool valued edge map of the the adapted graph.
+/// \tparam _Graph The type of the adapted graph.
-/// \tparam _checked If the parameter is false then the edge filtering
+/// It must conform to the \ref concepts::Graph "Graph" concept.
-/// is not checked with respect to node filter. Otherwise, each edge
+/// It can also be specified to be \c const.
-/// is automatically filtered, which is incident to a filtered node.
+/// \tparam _NodeFilterMap A \c bool (or convertible) node map of the
+/// adapted graph. The default map type is
+/// \ref concepts::Graph::NodeMap "_Graph::NodeMap<bool>".
+/// \tparam _EdgeFilterMap A \c bool (or convertible) edge map of the
+/// adapted graph. The default map type is
+/// \ref concepts::Graph::EdgeMap "_Graph::EdgeMap<bool>".
+/// \tparam _checked If this parameter is set to \c false, then the edge
+/// filtering is not checked with respect to the node filter.
+/// Otherwise, each edge that is incident to a hidden node is automatically
+/// filtered out. This is the default option.
+///
+/// \note The \c Node, \c Edge and \c Arc types of this adaptor and the
+/// adapted graph are convertible to each other.
 ///
 /// \see FilterNodes
 /// \see FilterEdges
-template<typename _Graph, typename NodeFilterMap,
+#ifdef DOXYGEN
-typename EdgeFilterMap, bool _checked = true>
+template<typename _Graph,
+typename _NodeFilterMap,
+typename _EdgeFilterMap,
+bool _checked>
+#else
+template<typename _Graph,
+typename _NodeFilterMap = typename _Graph::template NodeMap<bool>,
+typename _EdgeFilterMap = typename _Graph::template EdgeMap<bool>,
+bool _checked = true>
+#endif
 class SubGraph
 : public GraphAdaptorExtender<
-SubGraphBase<_Graph, NodeFilterMap, EdgeFilterMap, _checked> > {
+SubGraphBase<_Graph, _NodeFilterMap, _EdgeFilterMap, _checked> > {
 public:
+/// The type of the adapted graph.
 typedef _Graph Graph;
+/// The type of the node filter map.
+typedef _NodeFilterMap NodeFilterMap;
+/// The type of the edge filter map.
+typedef _EdgeFilterMap EdgeFilterMap;
 typedef GraphAdaptorExtender<
-SubGraphBase<_Graph, NodeFilterMap, EdgeFilterMap> > Parent;
+SubGraphBase<_Graph, _NodeFilterMap, _EdgeFilterMap, _checked> > Parent;
 typedef typename Parent::Node Node;
 typedef typename Parent::Edge Edge;
 protected:
 SubGraph() { }
 public:
 /// \brief Constructor
 ///
-/// Creates a subgraph for the given graph with given node and
+/// Creates a subgraph for the given graph with the given node
-/// edge map filters.
+/// and edge filter maps.
-SubGraph(Graph& _graph, NodeFilterMap& node_filter_map,
+SubGraph(Graph& graph, NodeFilterMap& node_filter_map,
 EdgeFilterMap& edge_filter_map) {
-setGraph(_graph);
+setGraph(graph);
 setNodeFilterMap(node_filter_map);
 setEdgeFilterMap(edge_filter_map);
 }
-/// \brief Hides the node of the graph
+/// \brief Hides the given node
 ///
-/// This function hides \c n in the graph, i.e. the iteration
+/// This function hides the given node in the subgraph,
-/// jumps over it. This is done by simply setting the value of \c n
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding node-map.
+/// It is done by simply setting the assigned value of \c n
+/// to be \c false in the node filter map.
 void hide(const Node& n) const { Parent::hide(n); }
-/// \brief Hides the edge of the graph
+/// \brief Hides the given edge
 ///
-/// This function hides \c e in the graph, i.e. the iteration
+/// This function hides the given edge in the subgraph,
-/// jumps over it. This is done by simply setting the value of \c e
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding edge-map.
+/// It is done by simply setting the assigned value of \c e
+/// to be \c false in the edge filter map.
 void hide(const Edge& e) const { Parent::hide(e); }
-/// \brief Unhides the node of the graph
+/// \brief Shows the given node
 ///
-/// The value of \c n is set to be true in the node-map which stores
+/// This function shows the given node in the subgraph.
-/// hide information. If \c n was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c n
-/// again
+/// to be \c true in the node filter map.
 void unHide(const Node& n) const { Parent::unHide(n); }
-/// \brief Unhides the edge of the graph
+/// \brief Shows the given edge
 ///
-/// The value of \c e is set to be true in the edge-map which stores
+/// This function shows the given edge in the subgraph.
-/// hide information. If \c e was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c e
-/// again
+/// to be \c true in the edge filter map.
 void unHide(const Edge& e) const { Parent::unHide(e); }
-/// \brief Returns true if \c n is hidden.
+/// \brief Returns \c true if the given node is hidden.
 ///
-/// Returns true if \c n is hidden.
+/// This function returns \c true if the given node is hidden.
-///
 bool hidden(const Node& n) const { return Parent::hidden(n); }
-/// \brief Returns true if \c e is hidden.
+/// \brief Returns \c true if the given edge is hidden.
 ///
-/// Returns true if \c e is hidden.
+/// This function returns \c true if the given edge is hidden.
-///
 bool hidden(const Edge& e) const { return Parent::hidden(e); }
 };
-/// \brief Just gives back a subgraph
+/// \brief Returns a read-only SubGraph adaptor
 ///
-/// Just gives back a subgraph
+/// This function just returns a read-only \ref SubGraph adaptor.
+/// \ingroup graph_adaptors
+/// \relates SubGraph
 template<typename Graph, typename NodeFilterMap, typename ArcFilterMap>
 SubGraph<const Graph, NodeFilterMap, ArcFilterMap>
 subGraph(const Graph& graph, NodeFilterMap& nfm, ArcFilterMap& efm) {
 return SubGraph<const Graph, NodeFilterMap, ArcFilterMap>(graph, nfm, efm);
 }
 const NodeFilterMap& nfm, const ArcFilterMap& efm) {
 return SubGraph<const Graph, const NodeFilterMap, const ArcFilterMap>
 (graph, nfm, efm);
 }
 /// \ingroup graph_adaptors
 ///
-/// \brief An adaptor for hiding nodes from a digraph or a graph.
+/// \brief Adaptor class for hiding nodes in a digraph or a graph.
 ///
-/// FilterNodes adaptor hides nodes in a graph or a digraph. A bool
+/// FilterNodes adaptor can be used for hiding nodes in a digraph or a
-/// node map must be specified, which defines the filters for
+/// graph. A \c bool node map must be specified, which defines the filter
-/// nodes. Just the unfiltered nodes and the arcs or edges incident
+/// for the nodes. Only the nodes with \c true filter value and the
-/// to unfiltered nodes are shown in the subdigraph or subgraph. The
+/// arcs/edges incident to nodes both with \c true filter value are shown
-/// FilterNodes is conform to the \ref concepts::Digraph
+/// in the subgraph. This adaptor conforms to the \ref concepts::Digraph
-/// "Digraph concept" or \ref concepts::Graph "Graph concept" depending
+/// "Digraph" concept or the \ref concepts::Graph "Graph" concept
-/// on the \c _Digraph template parameter. If the \c _checked
+/// depending on the \c _Graph template parameter.
-/// parameter is true, then the arc or edges incident to filtered nodes
+///
-/// are also filtered out.
+/// The adapted (di)graph can also be modified through this adaptor
-///
+/// by adding or removing nodes or arcs/edges, unless the \c _Graph template
-/// \tparam _Digraph It must be conform to the \ref
+/// parameter is set to be \c const.
-/// concepts::Digraph "Digraph concept" or \ref concepts::Graph
+///
-/// "Graph concept". The type can be specified to be const.
+/// \tparam _Graph The type of the adapted digraph or graph.
-/// \tparam _NodeFilterMap A bool valued node map of the the adapted graph.
+/// It must conform to the \ref concepts::Digraph "Digraph" concept
-/// \tparam _checked If the parameter is false then the arc or edge
+/// or the \ref concepts::Graph "Graph" concept.
-/// filtering is not checked with respect to node filter. In this
+/// It can also be specified to be \c const.
-/// case just isolated nodes can be filtered out from the
+/// \tparam _NodeFilterMap A \c bool (or convertible) node map of the
-/// graph.
+/// adapted (di)graph. The default map type is
+/// \ref concepts::Graph::NodeMap "_Graph::NodeMap<bool>".
+/// \tparam _checked If this parameter is set to \c false then the arc/edge
+/// filtering is not checked with respect to the node filter. In this
+/// case only isolated nodes can be filtered out from the graph.
+/// Otherwise, each arc/edge that is incident to a hidden node is
+/// automatically filtered out. This is the default option.
+///
+/// \note The \c Node and <tt>Arc/Edge</tt> types of this adaptor and the
+/// adapted (di)graph are convertible to each other.
 #ifdef DOXYGEN
-template<typename _Digraph,
+template<typename _Graph,
-typename _NodeFilterMap = typename _Digraph::template NodeMap<bool>,
+typename _NodeFilterMap,
-bool _checked = true>
+bool _checked>
 #else
 template<typename _Digraph,
 typename _NodeFilterMap = typename _Digraph::template NodeMap<bool>,
 bool _checked = true,
 typename Enable = void>
 public:
 /// \brief Constructor
 ///
-/// Creates an adaptor for the given digraph or graph with
+/// Creates a subgraph for the given digraph or graph with the
 /// given node filter map.
-FilterNodes(Digraph& _digraph, NodeFilterMap& node_filter) :
+#ifdef DOXYGEN
+FilterNodes(_Graph& graph, _NodeFilterMap& node_filter) :
+#else
+FilterNodes(Digraph& graph, NodeFilterMap& node_filter) :
+#endif
 Parent(), const_true_map(true) {
-Parent::setDigraph(_digraph);
+Parent::setDigraph(graph);
 Parent::setNodeFilterMap(node_filter);
 Parent::setArcFilterMap(const_true_map);
 }
-/// \brief Hides the node of the graph
+/// \brief Hides the given node
 ///
-/// This function hides \c n in the digraph or graph, i.e. the iteration
+/// This function hides the given node in the subgraph,
-/// jumps over it. This is done by simply setting the value of \c n
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding node map.
+/// It is done by simply setting the assigned value of \c n
+/// to be \c false in the node filter map.
 void hide(const Node& n) const { Parent::hide(n); }
-/// \brief Unhides the node of the graph
+/// \brief Shows the given node
 ///
-/// The value of \c n is set to be true in the node-map which stores
+/// This function shows the given node in the subgraph.
-/// hide information. If \c n was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c n
-/// again
+/// to be \c true in the node filter map.
 void unHide(const Node& n) const { Parent::unHide(n); }
-/// \brief Returns true if \c n is hidden.
+/// \brief Returns \c true if the given node is hidden.
 ///
-/// Returns true if \c n is hidden.
+/// This function returns \c true if the given node is hidden.
-///
 bool hidden(const Node& n) const { return Parent::hidden(n); }
 };
 template<typename _Graph, typename _NodeFilterMap, bool _checked>
 bool hidden(const Node& n) const { return Parent::hidden(n); }
 };
-/// \brief Just gives back a FilterNodes adaptor
+/// \brief Returns a read-only FilterNodes adaptor
 ///
-/// Just gives back a FilterNodes adaptor
+/// This function just returns a read-only \ref FilterNodes adaptor.
+/// \ingroup graph_adaptors
+/// \relates FilterNodes
 template<typename Digraph, typename NodeFilterMap>
 FilterNodes<const Digraph, NodeFilterMap>
 filterNodes(const Digraph& digraph, NodeFilterMap& nfm) {
 return FilterNodes<const Digraph, NodeFilterMap>(digraph, nfm);
 }
 return FilterNodes<const Digraph, const NodeFilterMap>(digraph, nfm);
 }
 /// \ingroup graph_adaptors
 ///
-/// \brief An adaptor for hiding arcs from a digraph.
+/// \brief Adaptor class for hiding arcs in a digraph.
 ///
-/// FilterArcs adaptor hides arcs in a digraph. A bool arc map must
+/// FilterArcs adaptor can be used for hiding arcs in a digraph.
-/// be specified, which defines the filters for arcs. Just the
+/// A \c bool arc map must be specified, which defines the filter for
-/// unfiltered arcs are shown in the subdigraph. The FilterArcs is
+/// the arcs. Only the arcs with \c true filter value are shown in the
-/// conform to the \ref concepts::Digraph "Digraph concept".
+/// subdigraph. This adaptor conforms to the \ref concepts::Digraph
-///
+/// "Digraph" concept.
-/// \tparam _Digraph It must be conform to the \ref concepts::Digraph
+///
-/// "Digraph concept". The type can be specified to be const.
+/// The adapted digraph can also be modified through this adaptor
-/// \tparam _ArcFilterMap A bool valued arc map of the the adapted
+/// by adding or removing nodes or arcs, unless the \c _Digraph template
-/// graph.
+/// parameter is set to be \c const.
-template<typename _Digraph, typename _ArcFilterMap>
+///
+/// \tparam _Digraph The type of the adapted digraph.
+/// It must conform to the \ref concepts::Digraph "Digraph" concept.
+/// It can also be specified to be \c const.
+/// \tparam _ArcFilterMap A \c bool (or convertible) arc map of the
+/// adapted digraph. The default map type is
+/// \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<bool>".
+///
+/// \note The \c Node and \c Arc types of this adaptor and the adapted
+/// digraph are convertible to each other.
+#ifdef DOXYGEN
+template<typename _Digraph,
+typename _ArcFilterMap>
+#else
+template<typename _Digraph,
+typename _ArcFilterMap = typename _Digraph::template ArcMap<bool> >
+#endif
 class FilterArcs :
 public SubDigraph<_Digraph, ConstMap<typename _Digraph::Node, bool>,
 _ArcFilterMap, false> {
 public:
 typedef _Digraph Digraph;
 typedef _ArcFilterMap ArcFilterMap;
 typedef SubDigraph<Digraph, ConstMap<typename Digraph::Node, bool>,
 ArcFilterMap, false> Parent;
 public:
 /// \brief Constructor
 ///
-/// Creates a FilterArcs adaptor for the given graph with
+/// Creates a subdigraph for the given digraph with the given arc
-/// given arc map filter.
+/// filter map.
 FilterArcs(Digraph& digraph, ArcFilterMap& arc_filter)
 : Parent(), const_true_map(true) {
 Parent::setDigraph(digraph);
 Parent::setNodeFilterMap(const_true_map);
 Parent::setArcFilterMap(arc_filter);
 }
-/// \brief Hides the arc of the graph
+/// \brief Hides the given arc
 ///
-/// This function hides \c a in the graph, i.e. the iteration
+/// This function hides the given arc in the subdigraph,
-/// jumps over it. This is done by simply setting the value of \c a
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding arc map.
+/// It is done by simply setting the assigned value of \c a
+/// to be \c false in the arc filter map.
 void hide(const Arc& a) const { Parent::hide(a); }
-/// \brief Unhides the arc of the graph
+/// \brief Shows the given arc
 ///
-/// The value of \c a is set to be true in the arc-map which stores
+/// This function shows the given arc in the subdigraph.
-/// hide information. If \c a was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c a
-/// again
+/// to be \c true in the arc filter map.
 void unHide(const Arc& a) const { Parent::unHide(a); }
-/// \brief Returns true if \c a is hidden.
+/// \brief Returns \c true if the given arc is hidden.
 ///
-/// Returns true if \c a is hidden.
+/// This function returns \c true if the given arc is hidden.
-///
 bool hidden(const Arc& a) const { return Parent::hidden(a); }
 };
-/// \brief Just gives back an FilterArcs adaptor
+/// \brief Returns a read-only FilterArcs adaptor
 ///
-/// Just gives back an FilterArcs adaptor
+/// This function just returns a read-only \ref FilterArcs adaptor.
+/// \ingroup graph_adaptors
+/// \relates FilterArcs
 template<typename Digraph, typename ArcFilterMap>
 FilterArcs<const Digraph, ArcFilterMap>
 filterArcs(const Digraph& digraph, ArcFilterMap& afm) {
 return FilterArcs<const Digraph, ArcFilterMap>(digraph, afm);
 }
 return FilterArcs<const Digraph, const ArcFilterMap>(digraph, afm);
 }
 /// \ingroup graph_adaptors
 ///
-/// \brief An adaptor for hiding edges from a graph.
+/// \brief Adaptor class for hiding edges in a graph.
 ///
-/// FilterEdges adaptor hides edges in a digraph. A bool edge map must
+/// FilterEdges adaptor can be used for hiding edges in a graph.
-/// be specified, which defines the filters for edges. Just the
+/// A \c bool edge map must be specified, which defines the filter for
-/// unfiltered edges are shown in the subdigraph. The FilterEdges is
+/// the edges. Only the edges with \c true filter value are shown in the
-/// conform to the \ref concepts::Graph "Graph concept".
+/// subgraph. This adaptor conforms to the \ref concepts::Graph
-///
+/// "Graph" concept.
-/// \tparam _Graph It must be conform to the \ref concepts::Graph
+///
-/// "Graph concept". The type can be specified to be const.
+/// The adapted graph can also be modified through this adaptor
-/// \tparam _EdgeFilterMap A bool valued edge map of the the adapted
+/// by adding or removing nodes or edges, unless the \c _Graph template
-/// graph.
+/// parameter is set to be \c const.
-template<typename _Graph, typename _EdgeFilterMap>
+///
+/// \tparam _Graph The type of the adapted graph.
+/// It must conform to the \ref concepts::Graph "Graph" concept.
+/// It can also be specified to be \c const.
+/// \tparam _EdgeFilterMap A \c bool (or convertible) edge map of the
+/// adapted graph. The default map type is
+/// \ref concepts::Graph::EdgeMap "_Graph::EdgeMap<bool>".
+///
+/// \note The \c Node, \c Edge and \c Arc types of this adaptor and the
+/// adapted graph are convertible to each other.
+#ifdef DOXYGEN
+template<typename _Graph,
+typename _EdgeFilterMap>
+#else
+template<typename _Graph,
+typename _EdgeFilterMap = typename _Graph::template EdgeMap<bool> >
+#endif
 class FilterEdges :
 public SubGraph<_Graph, ConstMap<typename _Graph::Node,bool>,
 _EdgeFilterMap, false> {
 public:
 typedef _Graph Graph;
 public:
 /// \brief Constructor
 ///
-/// Creates a FilterEdges adaptor for the given graph with
+/// Creates a subgraph for the given graph with the given edge
-/// given edge map filters.
+/// filter map.
-FilterEdges(Graph& _graph, EdgeFilterMap& edge_filter_map) :
+FilterEdges(Graph& graph, EdgeFilterMap& edge_filter_map) :
 Parent(), const_true_map(true) {
-Parent::setGraph(_graph);
+Parent::setGraph(graph);
 Parent::setNodeFilterMap(const_true_map);
 Parent::setEdgeFilterMap(edge_filter_map);
 }
-/// \brief Hides the edge of the graph
+/// \brief Hides the given edge
 ///
-/// This function hides \c e in the graph, i.e. the iteration
+/// This function hides the given edge in the subgraph,
-/// jumps over it. This is done by simply setting the value of \c e
+/// i.e. the iteration jumps over it.
-/// to be false in the corresponding edge-map.
+/// It is done by simply setting the assigned value of \c e
+/// to be \c false in the edge filter map.
 void hide(const Edge& e) const { Parent::hide(e); }
-/// \brief Unhides the edge of the graph
+/// \brief Shows the given edge
 ///
-/// The value of \c e is set to be true in the edge-map which stores
+/// This function shows the given edge in the subgraph.
-/// hide information. If \c e was hidden previuosly, then it is shown
+/// It is done by simply setting the assigned value of \c e
-/// again
+/// to be \c true in the edge filter map.
 void unHide(const Edge& e) const { Parent::unHide(e); }
-/// \brief Returns true if \c e is hidden.
+/// \brief Returns \c true if the given edge is hidden.
 ///
-/// Returns true if \c e is hidden.
+/// This function returns \c true if the given edge is hidden.
-///
 bool hidden(const Edge& e) const { return Parent::hidden(e); }
 };
-/// \brief Just gives back a FilterEdges adaptor
+/// \brief Returns a read-only FilterEdges adaptor
 ///
-/// Just gives back a FilterEdges adaptor
+/// This function just returns a read-only \ref FilterEdges adaptor.
+/// \ingroup graph_adaptors
+/// \relates FilterEdges
 template<typename Graph, typename EdgeFilterMap>
 FilterEdges<const Graph, EdgeFilterMap>
 filterEdges(const Graph& graph, EdgeFilterMap& efm) {
 return FilterEdges<const Graph, EdgeFilterMap>(graph, efm);
 }
 FilterEdges<const Graph, const EdgeFilterMap>
 filterEdges(const Graph& graph, const EdgeFilterMap& efm) {
 return FilterEdges<const Graph, const EdgeFilterMap>(graph, efm);
 }
 template <typename _Digraph>
 class UndirectorBase {
 public:
 typedef _Digraph Digraph;
 typedef UndirectorBase Adaptor;
 return _forward < other._forward ||
 (_forward == other._forward &&
 static_cast<const Edge&>(*this) < static_cast<const Edge&>(other));
 }
 };
 void first(Node& n) const {
 _digraph->first(n);
 }
 };
 /// \ingroup graph_adaptors
 ///
-/// \brief Undirect the graph
+/// \brief Adaptor class for viewing a digraph as an undirected graph.
 ///
-/// This adaptor makes an undirected graph from a directed
+/// Undirector adaptor can be used for viewing a digraph as an undirected
-/// graph. All arcs of the underlying digraph will be showed in the
+/// graph. All arcs of the underlying digraph are showed in the
-/// adaptor as an edge. The Orienter adaptor is conform to the \ref
+/// adaptor as an edge (and also as a pair of arcs, of course).
-/// concepts::Graph "Graph concept".
+/// This adaptor conforms to the \ref concepts::Graph "Graph" concept.
 ///
-/// \tparam _Digraph It must be conform to the \ref
+/// The adapted digraph can also be modified through this adaptor
-/// concepts::Digraph "Digraph concept". The type can be specified
+/// by adding or removing nodes or edges, unless the \c _Digraph template
-/// to const.
+/// parameter is set to be \c const.
+///
+/// \tparam _Digraph The type of the adapted digraph.
+/// It must conform to the \ref concepts::Digraph "Digraph" concept.
+/// It can also be specified to be \c const.
+///
+/// \note The \c Node type of this adaptor and the adapted digraph are
+/// convertible to each other, moreover the \c Edge type of the adaptor
+/// and the \c Arc type of the adapted digraph are also convertible to
+/// each other.
+/// (Thus the \c Arc type of the adaptor is convertible to the \c Arc type
+/// of the adapted digraph.)
 template<typename _Digraph>
 class Undirector
 : public GraphAdaptorExtender<UndirectorBase<_Digraph> > {
 public:
 typedef _Digraph Digraph;
 Undirector() { }
 public:
 /// \brief Constructor
 ///
-/// Creates a undirected graph from the given digraph
+/// Creates an undirected graph from the given digraph.
 Undirector(_Digraph& digraph) {
 setDigraph(digraph);
 }
-/// \brief ArcMap combined from two original ArcMap
+/// \brief Arc map combined from two original arc maps
 ///
-/// This class adapts two original digraph ArcMap to
+/// This map adaptor class adapts two arc maps of the underlying
-/// get an arc map on the undirected graph.
+/// digraph to get an arc map of the undirected graph.
+/// Its value type is inherited from the first arc map type
+/// (\c %ForwardMap).
 template <typename _ForwardMap, typename _BackwardMap>
 class CombinedArcMap {
 public:
 typedef _ForwardMap ForwardMap;
 typedef _BackwardMap BackwardMap;
 typedef typename MapTraits<ForwardMap>::ReferenceMapTag ReferenceMapTag;
+/// The key type of the map
+typedef typename Parent::Arc Key;
+/// The value type of the map
 typedef typename ForwardMap::Value Value;
-typedef typename Parent::Arc Key;
 typedef typename MapTraits<ForwardMap>::ReturnValue ReturnValue;
 typedef typename MapTraits<ForwardMap>::ConstReturnValue ConstReturnValue;
 typedef typename MapTraits<ForwardMap>::ReturnValue Reference;
 typedef typename MapTraits<ForwardMap>::ConstReturnValue ConstReference;
-/// \brief Constructor
-///
 /// Constructor
 CombinedArcMap(ForwardMap& forward, BackwardMap& backward)
 : _forward(&forward), _backward(&backward) {}
+/// Sets the value associated with the given key.
-/// \brief Sets the value associated with a key.
-///
-/// Sets the value associated with a key.
 void set(const Key& e, const Value& a) {
 if (Parent::direction(e)) {
 _forward->set(e, a);
 } else {
 _backward->set(e, a);
 }
 }
-/// \brief Returns the value associated with a key.
+/// Returns the value associated with the given key.
-///
-/// Returns the value associated with a key.
 ConstReturnValue operator[](const Key& e) const {
 if (Parent::direction(e)) {
 return (*_forward)[e];
 } else {
 return (*_backward)[e];
 }
 }
-/// \brief Returns the value associated with a key.
+/// Returns a reference to the value associated with the given key.
-///
-/// Returns the value associated with a key.
 ReturnValue operator[](const Key& e) {
 if (Parent::direction(e)) {
 return (*_forward)[e];
 } else {
 return (*_backward)[e];
 ForwardMap* _forward;
 BackwardMap* _backward;
 };
-/// \brief Just gives back a combined arc map
+/// \brief Returns a combined arc map
 ///
-/// Just gives back a combined arc map
+/// This function just returns a combined arc map.
 template <typename ForwardMap, typename BackwardMap>
 static CombinedArcMap<ForwardMap, BackwardMap>
 combinedArcMap(ForwardMap& forward, BackwardMap& backward) {
 return CombinedArcMap<ForwardMap, BackwardMap>(forward, backward);
 }
 const BackwardMap>(forward, backward);
 }
 };
-/// \brief Just gives back an undirected view of the given digraph
+/// \brief Returns a read-only Undirector adaptor
 ///
-/// Just gives back an undirected view of the given digraph
+/// This function just returns a read-only \ref Undirector adaptor.
+/// \ingroup graph_adaptors
+/// \relates Undirector
 template<typename Digraph>
 Undirector<const Digraph>
 undirector(const Digraph& digraph) {
 return Undirector<const Digraph>(digraph);
 }
 template <typename _Graph, typename _DirectionMap>
 class OrienterBase {
 public:
 };
 /// \ingroup graph_adaptors
 ///
-/// \brief Orients the edges of the graph to get a digraph
+/// \brief Adaptor class for orienting the edges of a graph to get a digraph
 ///
-/// This adaptor orients each edge in the undirected graph. The
+/// Orienter adaptor can be used for orienting the edges of a graph to
-/// direction of the arcs stored in an edge node map.  The arcs can
+/// get a digraph. A \c bool edge map of the underlying graph must be
-/// be easily reverted by the \c reverseArc() member function in the
+/// specified, which define the direction of the arcs in the adaptor.
-/// adaptor. The Orienter adaptor is conform to the \ref
+/// The arcs can be easily reversed by the \c reverseArc() member function
-/// concepts::Digraph "Digraph concept".
+/// of the adaptor.
-///
+/// This class conforms to the \ref concepts::Digraph "Digraph" concept.
-/// \tparam _Graph It must be conform to the \ref concepts::Graph
+///
-/// "Graph concept". The type can be specified to be const.
+/// The adapted graph can also be modified through this adaptor
-/// \tparam _DirectionMap A bool valued edge map of the the adapted
+/// by adding or removing nodes or arcs, unless the \c _Graph template
-/// graph.
+/// parameter is set to be \c const.
 ///
-/// \sa orienter
+/// \tparam _Graph The type of the adapted graph.
+/// It must conform to the \ref concepts::Graph "Graph" concept.
+/// It can also be specified to be \c const.
+/// \tparam _DirectionMap A \c bool (or convertible) edge map of the
+/// adapted graph. The default map type is
+/// \ref concepts::Graph::EdgeMap "_Graph::EdgeMap<bool>".
+///
+/// \note The \c Node type of this adaptor and the adapted graph are
+/// convertible to each other, moreover the \c Arc type of the adaptor
+/// and the \c Edge type of the adapted graph are also convertible to
+/// each other.
+#ifdef DOXYGEN
 template<typename _Graph,
-typename DirectionMap = typename _Graph::template EdgeMap<bool> >
+typename _DirectionMap>
+#else
+template<typename _Graph,
+typename _DirectionMap = typename _Graph::template EdgeMap<bool> >
+#endif
 class Orienter :
-public DigraphAdaptorExtender<OrienterBase<_Graph, DirectionMap> > {
+public DigraphAdaptorExtender<OrienterBase<_Graph, _DirectionMap> > {
 public:
+/// The type of the adapted graph.
 typedef _Graph Graph;
+/// The type of the direction edge map.
+typedef _DirectionMap DirectionMap;
 typedef DigraphAdaptorExtender<
-OrienterBase<_Graph, DirectionMap> > Parent;
+OrienterBase<_Graph, _DirectionMap> > Parent;
 typedef typename Parent::Arc Arc;
 protected:
 Orienter() { }
 public:
-/// \brief Constructor of the adaptor
+/// \brief Constructor
 ///
-/// Constructor of the adaptor
+/// Constructor of the adaptor.
 Orienter(Graph& graph, DirectionMap& direction) {
 setGraph(graph);
 setDirectionMap(direction);
 }
-/// \brief Reverse arc
+/// \brief Reverses the given arc
 ///
-/// It reverse the given arc. It simply negate the direction in the map.
+/// This function reverses the given arc.
+/// It is done by simply negate the assigned value of \c a
+/// in the direction map.
 void reverseArc(const Arc& a) {
 Parent::reverseArc(a);
 }
 };
-/// \brief Just gives back a Orienter
+/// \brief Returns a read-only Orienter adaptor
 ///
-/// Just gives back a Orienter
+/// This function just returns a read-only \ref Orienter adaptor.
+/// \ingroup graph_adaptors
+/// \relates Orienter
 template<typename Graph, typename DirectionMap>
 Orienter<const Graph, DirectionMap>
 orienter(const Graph& graph, DirectionMap& dm) {
 return Orienter<const Graph, DirectionMap>(graph, dm);
 }
 }
 /// \ingroup graph_adaptors
 ///
-/// \brief An adaptor for composing the residual graph for directed
+/// \brief Adaptor class for composing the residual digraph for directed
 /// flow and circulation problems.
 ///
-/// An adaptor for composing the residual graph for directed flow and
+/// Residual can be used for composing the \e residual digraph for directed
-/// circulation problems.  Let \f$ G=(V, A) \f$ be a directed graph
+/// flow and circulation problems. Let \f$ G=(V, A) \f$ be a directed graph
-/// and let \f$ F \f$ be a number type. Let moreover \f$ f,c:A\to F \f$,
+/// and let \f$ F \f$ be a number type. Let \f$ flow, cap: A\to F \f$ be
-/// be functions on the arc-set.
+/// functions on the arcs.
-///
+/// This adaptor implements a digraph structure with node set \f$ V \f$
-/// Then Residual implements the digraph structure with
+/// and arc set \f$ A_{forward}\cup A_{backward} \f$,
-/// node-set \f$ V \f$ and arc-set \f$ A_{forward}\cup A_{backward} \f$,
+/// where \f$ A_{forward}=\{uv : uv\in A, flow(uv)<cap(uv)\} \f$ and
-/// where \f$ A_{forward}=\{uv : uv\in A, f(uv)<c(uv)\} \f$ and
+/// \f$ A_{backward}=\{vu : uv\in A, flow(uv)>0\} \f$, i.e. the so
-/// \f$ A_{backward}=\{vu : uv\in A, f(uv)>0\} \f$, i.e. the so
+/// called residual digraph.
-/// called residual graph.  When we take the union
+/// When the union \f$ A_{forward}\cup A_{backward} \f$ is taken,
-/// \f$ A_{forward}\cup A_{backward} \f$, multiplicities are counted,
+/// multiplicities are counted, i.e. the adaptor has exactly
-/// i.e.  if an arc is in both \f$ A_{forward} \f$ and
+/// \f$ |A_{forward}| + |A_{backward}|\f$ arcs (it may have parallel
-/// \f$ A_{backward} \f$, then in the adaptor it appears in both
+/// arcs).
-/// orientation.
+/// This class conforms to the \ref concepts::Digraph "Digraph" concept.
 ///
-/// \tparam _Digraph It must be conform to the \ref concepts::Digraph
+/// \tparam _Digraph The type of the adapted digraph.
-/// "Digraph concept". The type is implicitly const.
+/// It must conform to the \ref concepts::Digraph "Digraph" concept.
-/// \tparam _CapacityMap An arc map of some numeric type, it defines
+/// It is implicitly \c const.
-/// the capacities in the flow problem. The map is implicitly const.
+/// \tparam _CapacityMap An arc map of some numerical type, which defines
-/// \tparam _FlowMap An arc map of some numeric type, it defines
+/// the capacities in the flow problem. It is implicitly \c const.
-/// the capacities in the flow problem.
+/// The default map type is
-/// \tparam _Tolerance Handler for inexact computation.
+/// \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<int>".
+/// \tparam _FlowMap An arc map of some numerical type, which defines
+/// the flow values in the flow problem.
+/// The default map type is \c _CapacityMap.
+/// \tparam _Tolerance Tolerance type for handling inexact computation.
+/// The default tolerance type depends on the value type of the
+/// capacity map.
+///
+/// \note This adaptor is implemented using Undirector and FilterArcs
+/// adaptors.
+///
+/// \note The \c Node type of this adaptor and the adapted digraph are
+/// convertible to each other, moreover the \c Arc type of the adaptor
+/// is convertible to the \c Arc type of the adapted digraph.
+#ifdef DOXYGEN
+template<typename _Digraph,
+typename _CapacityMap,
+typename _FlowMap,
+typename _Tolerance>
+class Residual
+#else
 template<typename _Digraph,
 typename _CapacityMap = typename _Digraph::template ArcMap<int>,
 typename _FlowMap = _CapacityMap,
 typename _Tolerance = Tolerance<typename _CapacityMap::Value> >
 class Residual :
 typename Undirector<const _Digraph>::template CombinedArcMap<
 _adaptor_bits::ResForwardFilter<const _Digraph, _CapacityMap,
 _FlowMap, _Tolerance>,
 _adaptor_bits::ResBackwardFilter<const _Digraph, _CapacityMap,
 _FlowMap, _Tolerance> > >
+#endif
 {
 public:
+/// The type of the underlying digraph.
 typedef _Digraph Digraph;
+/// The type of the capacity map.
 typedef _CapacityMap CapacityMap;
+/// The type of the flow map.
 typedef _FlowMap FlowMap;
 typedef _Tolerance Tolerance;
 typedef typename CapacityMap::Value Value;
 typedef Residual Adaptor;
 BackwardFilter _backward_filter;
 ArcFilter _arc_filter;
 public:
-/// \brief Constructor of the residual digraph.
+/// \brief Constructor
 ///
-/// Constructor of the residual graph. The parameters are the digraph,
+/// Constructor of the residual digraph adaptor. The parameters are the
-/// the flow map, the capacity map and a tolerance object.
+/// digraph, the capacity map, the flow map, and a tolerance object.
 Residual(const Digraph& digraph, const CapacityMap& capacity,
 FlowMap& flow, const Tolerance& tolerance = Tolerance())
 : Parent(), _capacity(&capacity), _flow(&flow), _graph(digraph),
 _forward_filter(capacity, flow, tolerance),
 _backward_filter(capacity, flow, tolerance),
 Parent::setArcFilterMap(_arc_filter);
 }
 typedef typename Parent::Arc Arc;
-/// \brief Gives back the residual capacity of the arc.
+/// \brief Returns the residual capacity of the given arc.
 ///
-/// Gives back the residual capacity of the arc.
+/// Returns the residual capacity of the given arc.
 Value residualCapacity(const Arc& a) const {
 if (Undirected::direction(a)) {
 return (*_capacity)[a] - (*_flow)[a];
 } else {
 return (*_flow)[a];
 }
 }
-/// \brief Augment on the given arc in the residual graph.
+/// \brief Augment on the given arc in the residual digraph.
 ///
-/// Augment on the given arc in the residual graph. It increase
+/// Augment on the given arc in the residual digraph. It increases
-/// or decrease the flow on the original arc depend on the direction
+/// or decreases the flow value on the original arc according to the
-/// of the residual arc.
+/// direction of the residual arc.
 void augment(const Arc& a, const Value& v) const {
 if (Undirected::direction(a)) {
 _flow->set(a, (*_flow)[a] + v);
 } else {
 _flow->set(a, (*_flow)[a] - v);
 }
 }
-/// \brief Returns the direction of the arc.
+/// \brief Returns \c true if the given residual arc is a forward arc.
 ///
-/// Returns true when the arc is same oriented as the original arc.
+/// Returns \c true if the given residual arc has the same orientation
+/// as the original arc, i.e. it is a so called forward arc.
 static bool forward(const Arc& a) {
 return Undirected::direction(a);
 }
-/// \brief Returns the direction of the arc.
+/// \brief Returns \c true if the given residual arc is a backward arc.
 ///
-/// Returns true when the arc is opposite oriented as the original arc.
+/// Returns \c true if the given residual arc has the opposite orientation
+/// than the original arc, i.e. it is a so called backward arc.
 static bool backward(const Arc& a) {
 return !Undirected::direction(a);
 }
-/// \brief Gives back the forward oriented residual arc.
+/// \brief Returns the forward oriented residual arc.
 ///
-/// Gives back the forward oriented residual arc.
+/// Returns the forward oriented residual arc related to the given
+/// arc of the underlying digraph.
 static Arc forward(const typename Digraph::Arc& a) {
 return Undirected::direct(a, true);
 }
-/// \brief Gives back the backward oriented residual arc.
+/// \brief Returns the backward oriented residual arc.
 ///
-/// Gives back the backward oriented residual arc.
+/// Returns the backward oriented residual arc related to the given
+/// arc of the underlying digraph.
 static Arc backward(const typename Digraph::Arc& a) {
 return Undirected::direct(a, false);
 }
 /// \brief Residual capacity map.
 ///
-/// In generic residual graph the residual capacity can be obtained
+/// This map adaptor class can be used for obtaining the residual
-/// as a map.
+/// capacities as an arc map of the residual digraph.
+/// Its value type is inherited from the capacity map.
 class ResidualCapacity {
 protected:
 const Adaptor* _adaptor;
 public:
-/// The Key type
+/// The key type of the map
 typedef Arc Key;
-/// The Value type
+/// The value type of the map
 typedef typename _CapacityMap::Value Value;
 /// Constructor
 ResidualCapacity(const Adaptor& adaptor) : _adaptor(&adaptor) {}
-/// \e
+/// Returns the value associated with the given residual arc
 Value operator[](const Arc& a) const {
 return _adaptor->residualCapacity(a);
 }
 };
 };
 /// \ingroup graph_adaptors
 ///
-/// \brief Split the nodes of a directed graph
+/// \brief Adaptor class for splitting the nodes of a digraph.
 ///
-/// The SplitNodes adaptor splits each node into an in-node and an
+/// SplitNodes adaptor can be used for splitting each node into an
-/// out-node. Formaly, the adaptor replaces each \f$ u \f$ node in
+/// \e in-node and an \e out-node in a digraph. Formaly, the adaptor
-/// the digraph with two nodes(namely node \f$ u_{in} \f$ and node
+/// replaces each node \f$ u \f$ in the digraph with two nodes,
-/// \f$ u_{out} \f$). If there is a \f$ (v, u) \f$ arc in the
+/// namely node \f$ u_{in} \f$ and node \f$ u_{out} \f$.
-/// original digraph the new target of the arc will be \f$ u_{in} \f$
+/// If there is a \f$ (v, u) \f$ arc in the original digraph, then the
-/// and similarly the source of the original \f$ (u, v) \f$ arc
+/// new target of the arc will be \f$ u_{in} \f$ and similarly the
-/// will be \f$ u_{out} \f$.  The adaptor will add for each node in
+/// source of each original \f$ (u, v) \f$ arc will be \f$ u_{out} \f$.
-/// the original digraph an additional arc which connects
+/// The adaptor adds an additional \e bind \e arc from \f$ u_{in} \f$
-/// \f$ (u_{in}, u_{out}) \f$.
+/// to \f$ u_{out} \f$ for each node \f$ u \f$ of the original digraph.
 ///
-/// The aim of this class is to run algorithm with node costs if the
+/// The aim of this class is running an algorithm with respect to node
-/// algorithm can use directly just arc costs. In this case we should use
+/// costs or capacities if the algorithm considers only arc costs or
-/// a \c SplitNodes and set the node cost of the graph to the
+/// capacities directly.
-/// bind arc in the adapted graph.
+/// In this case you can use \c SplitNodes adaptor, and set the node
-///
+/// costs/capacities of the original digraph to the \e bind \e arcs
-/// \tparam _Digraph It must be conform to the \ref concepts::Digraph
+/// in the adaptor.
-/// "Digraph concept". The type can be specified to be const.
+///
+/// \tparam _Digraph The type of the adapted digraph.
+/// It must conform to the \ref concepts::Digraph "Digraph" concept.
+/// It is implicitly \c const.
+///
+/// \note The \c Node type of this adaptor is converible to the \c Node
+/// type of the adapted digraph.
 template <typename _Digraph>
 class SplitNodes
 : public DigraphAdaptorExtender<SplitNodesBase<const _Digraph> > {
 public:
 typedef _Digraph Digraph;
 typedef typename Digraph::Arc DigraphArc;
 typedef typename Parent::Node Node;
 typedef typename Parent::Arc Arc;
-/// \brief Constructor of the adaptor.
+/// \brief Constructor
 ///
 /// Constructor of the adaptor.
 SplitNodes(const Digraph& g) {
 Parent::setDigraph(g);
 }
-/// \brief Returns true when the node is in-node.
+/// \brief Returns \c true if the given node is an in-node.
 ///
-/// Returns true when the node is in-node.
+/// Returns \c true if the given node is an in-node.
 static bool inNode(const Node& n) {
 return Parent::inNode(n);
 }
-/// \brief Returns true when the node is out-node.
+/// \brief Returns \c true if the given node is an out-node.
 ///
-/// Returns true when the node is out-node.
+/// Returns \c true if the given node is an out-node.
 static bool outNode(const Node& n) {
 return Parent::outNode(n);
 }
-/// \brief Returns true when the arc is arc in the original digraph.
+/// \brief Returns \c true if the given arc is an original arc.
 ///
-/// Returns true when the arc is arc in the original digraph.
+/// Returns \c true if the given arc is one of the arcs in the
+/// original digraph.
 static bool origArc(const Arc& a) {
 return Parent::origArc(a);
 }
-/// \brief Returns true when the arc binds an in-node and an out-node.
+/// \brief Returns \c true if the given arc is a bind arc.
 ///
-/// Returns true when the arc binds an in-node and an out-node.
+/// Returns \c true if the given arc is a bind arc, i.e. it connects
+/// an in-node and an out-node.
 static bool bindArc(const Arc& a) {
 return Parent::bindArc(a);
 }
-/// \brief Gives back the in-node created from the \c node.
+/// \brief Returns the in-node created from the given original node.
 ///
-/// Gives back the in-node created from the \c node.
+/// Returns the in-node created from the given original node.
 static Node inNode(const DigraphNode& n) {
 return Parent::inNode(n);
 }
-/// \brief Gives back the out-node created from the \c node.
+/// \brief Returns the out-node created from the given original node.
 ///
-/// Gives back the out-node created from the \c node.
+/// Returns the out-node created from the given original node.
 static Node outNode(const DigraphNode& n) {
 return Parent::outNode(n);
 }
-/// \brief Gives back the arc binds the two part of the node.
+/// \brief Returns the bind arc that corresponds to the given
-///
+/// original node.
-/// Gives back the arc binds the two part of the node.
+///
+/// Returns the bind arc in the adaptor that corresponds to the given
+/// original node, i.e. the arc connecting the in-node and out-node
+/// of \c n.
 static Arc arc(const DigraphNode& n) {
 return Parent::arc(n);
 }
-/// \brief Gives back the arc of the original arc.
+/// \brief Returns the arc that corresponds to the given original arc.
 ///
-/// Gives back the arc of the original arc.
+/// Returns the arc in the adaptor that corresponds to the given
+/// original arc.
 static Arc arc(const DigraphArc& a) {
 return Parent::arc(a);
 }
-/// \brief NodeMap combined from two original NodeMap
+/// \brief Node map combined from two original node maps
 ///
-/// This class adapt two of the original digraph NodeMap to
+/// This map adaptor class adapts two node maps of the original digraph
-/// get a node map on the adapted digraph.
+/// to get a node map of the split digraph.
+/// Its value type is inherited from the first node map type
+/// (\c InNodeMap).
 template <typename InNodeMap, typename OutNodeMap>
 class CombinedNodeMap {
 public:
+/// The key type of the map
 typedef Node Key;
+/// The value type of the map
 typedef typename InNodeMap::Value Value;
 typedef typename MapTraits<InNodeMap>::ReferenceMapTag ReferenceMapTag;
 typedef typename MapTraits<InNodeMap>::ReturnValue ReturnValue;
 typedef typename MapTraits<InNodeMap>::ConstReturnValue ConstReturnValue;
 typedef typename MapTraits<InNodeMap>::ReturnValue Reference;
 typedef typename MapTraits<InNodeMap>::ConstReturnValue ConstReference;
-/// \brief Constructor
+/// Constructor
-///
-/// Constructor.
 CombinedNodeMap(InNodeMap& in_map, OutNodeMap& out_map)
 : _in_map(in_map), _out_map(out_map) {}
-/// \brief The subscript operator.
+/// Returns the value associated with the given key.
-///
+Value operator[](const Key& key) const {
-/// The subscript operator.
+if (Parent::inNode(key)) {
+return _in_map[key];
+} else {
+return _out_map[key];
+}
+}
+/// Returns a reference to the value associated with the given key.
 Value& operator[](const Key& key) {
 if (Parent::inNode(key)) {
 return _in_map[key];
 } else {
 return _out_map[key];
 }
 }
-/// \brief The const subscript operator.
+/// Sets the value associated with the given key.
-///
-/// The const subscript operator.
-Value operator[](const Key& key) const {
-if (Parent::inNode(key)) {
-return _in_map[key];
-} else {
-return _out_map[key];
-}
-}
-/// \brief The setter function of the map.
-///
-/// The setter function of the map.
 void set(const Key& key, const Value& value) {
 if (Parent::inNode(key)) {
 _in_map.set(key, value);
 } else {
 _out_map.set(key, value);
 OutNodeMap& _out_map;
 };
-/// \brief Just gives back a combined node map
+/// \brief Returns a combined node map
 ///
-/// Just gives back a combined node map
+/// This function just returns a combined node map.
 template <typename InNodeMap, typename OutNodeMap>
 static CombinedNodeMap<InNodeMap, OutNodeMap>
 combinedNodeMap(InNodeMap& in_map, OutNodeMap& out_map) {
 return CombinedNodeMap<InNodeMap, OutNodeMap>(in_map, out_map);
 }
 combinedNodeMap(const InNodeMap& in_map, const OutNodeMap& out_map) {
 return CombinedNodeMap<const InNodeMap,
 const OutNodeMap>(in_map, out_map);
 }
-/// \brief ArcMap combined from an original ArcMap and a NodeMap
+/// \brief Arc map combined from an arc map and a node map of the
-///
+/// original digraph.
-/// This class adapt an original ArcMap and a NodeMap to get an
+///
-/// arc map on the adapted digraph
+/// This map adaptor class adapts an arc map and a node map of the
+/// original digraph to get an arc map of the split digraph.
+/// Its value type is inherited from the original arc map type
+/// (\c DigraphArcMap).
 template <typename DigraphArcMap, typename DigraphNodeMap>
 class CombinedArcMap {
 public:
+/// The key type of the map
 typedef Arc Key;
+/// The value type of the map
 typedef typename DigraphArcMap::Value Value;
 typedef typename MapTraits<DigraphArcMap>::ReferenceMapTag
 ReferenceMapTag;
 typedef typename MapTraits<DigraphArcMap>::ReturnValue
 typedef typename MapTraits<DigraphArcMap>::ReturnValue
 Reference;
 typedef typename MapTraits<DigraphArcMap>::ConstReturnValue
 ConstReference;
-/// \brief Constructor
+/// Constructor
-///
-/// Constructor.
 CombinedArcMap(DigraphArcMap& arc_map, DigraphNodeMap& node_map)
 : _arc_map(arc_map), _node_map(node_map) {}
-/// \brief The subscript operator.
+/// Returns the value associated with the given key.
-///
+Value operator[](const Key& arc) const {
-/// The subscript operator.
+if (Parent::origArc(arc)) {
+return _arc_map[arc];
+} else {
+return _node_map[arc];
+}
+}
+/// Returns a reference to the value associated with the given key.
+Value& operator[](const Key& arc) {
+if (Parent::origArc(arc)) {
+return _arc_map[arc];
+} else {
+return _node_map[arc];
+}
+}
+/// Sets the value associated with the given key.
 void set(const Arc& arc, const Value& val) {
 if (Parent::origArc(arc)) {
 _arc_map.set(arc, val);
 } else {
 _node_map.set(arc, val);
 }
 }
-/// \brief The const subscript operator.
-///
-/// The const subscript operator.
-Value operator[](const Key& arc) const {
-if (Parent::origArc(arc)) {
-return _arc_map[arc];
-} else {
-return _node_map[arc];
-}
-}
-/// \brief The const subscript operator.
-///
-/// The const subscript operator.
-Value& operator[](const Key& arc) {
-if (Parent::origArc(arc)) {
-return _arc_map[arc];
-} else {
-return _node_map[arc];
-}
-}
 private:
 DigraphArcMap& _arc_map;
 DigraphNodeMap& _node_map;
 };
-/// \brief Just gives back a combined arc map
+/// \brief Returns a combined arc map
 ///
-/// Just gives back a combined arc map
+/// This function just returns a combined arc map.
 template <typename DigraphArcMap, typename DigraphNodeMap>
 static CombinedArcMap<DigraphArcMap, DigraphNodeMap>
 combinedArcMap(DigraphArcMap& arc_map, DigraphNodeMap& node_map) {
 return CombinedArcMap<DigraphArcMap, DigraphNodeMap>(arc_map, node_map);
 }
 const DigraphNodeMap>(arc_map, node_map);
 }
 };
-/// \brief Just gives back a node splitter
+/// \brief Returns a (read-only) SplitNodes adaptor
 ///
-/// Just gives back a node splitter
+/// This function just returns a (read-only) \ref SplitNodes adaptor.
+/// \ingroup graph_adaptors
+/// \relates SplitNodes
 template<typename Digraph>
 SplitNodes<Digraph>
 splitNodes(const Digraph& digraph) {
 return SplitNodes<Digraph>(digraph);
 }

changeset 474	fbd6e04acf44
parent 473	14bb8812b8af
child 475	aea2dc0518ce