author Peter Kovacs Fri, 09 Jan 2009 12:54:27 +0100 changeset 474 fbd6e04acf44 parent 473 14bb8812b8af child 475 aea2dc0518ce
Various doc improvements for graph adaptors (#67)

if it is possible.
- Add notes about the possible conversions between the Node, Arc and
- Hide the default values for template parameters (describe them
- More precise docs for template parameters.
- More precise docs for member functions.
- Add docs for important public typedefs.
- Unify the docs of the adaptors.
- Add \relates commands for the creator functions.
- Fixes and improvements the module documentation.
 doc/groups.dox file | annotate | diff | comparison | revisions lemon/adaptors.h file | annotate | diff | comparison | revisions
1.1 --- a/doc/groups.dox	Fri Jan 09 12:43:52 2009 +0100
1.2 +++ b/doc/groups.dox	Fri Jan 09 12:54:27 2009 +0100
1.3 @@ -62,18 +62,20 @@
1.4  */
1.6  /**
1.9  @ingroup graphs
1.10 -\brief This group contains several adaptor classes for digraphs and graphs
1.11 +\brief Adaptor classes for digraphs and graphs
1.12 +
1.13 +This group contains several useful adaptor classes for digraphs and graphs.
1.15  The main parts of LEMON are the different graph structures, generic
1.16 -graph algorithms, graph concepts which couple these, and graph
1.17 +graph algorithms, graph concepts, which couple them, and graph
1.18  adaptors. While the previous notions are more or less clear, the
1.19  latter one needs further explanation. Graph adaptors are graph classes
1.20  which serve for considering graph structures in different ways.
1.22  A short example makes this much clearer.  Suppose that we have an
1.23 -instance \c g of a directed graph type say ListDigraph and an algorithm
1.24 +instance \c g of a directed graph type, say ListDigraph and an algorithm
1.25  \code
1.26  template <typename Digraph>
1.27  int algorithm(const Digraph&);
1.28 @@ -81,13 +83,13 @@
1.29  is needed to run on the reverse oriented graph.  It may be expensive
1.30  (in time or in memory usage) to copy \c g with the reversed
1.31  arcs.  In this case, an adaptor class is used, which (according
1.32 -to LEMON digraph concepts) works as a digraph.  The adaptor uses the
1.33 -original digraph structure and digraph operations when methods of the
1.34 -reversed oriented graph are called.  This means that the adaptor have
1.35 -minor memory usage, and do not perform sophisticated algorithmic
1.36 +to LEMON \ref concepts::Digraph "digraph concepts") works as a digraph.
1.37 +The adaptor uses the original digraph structure and digraph operations when
1.38 +methods of the reversed oriented graph are called.  This means that the adaptor
1.39 +have minor memory usage, and do not perform sophisticated algorithmic
1.40  actions.  The purpose of it is to give a tool for the cases when a
1.41  graph have to be used in a specific alteration.  If this alteration is
1.42 -obtained by a usual construction like filtering the arc-set or
1.43 +obtained by a usual construction like filtering the node or the arc set or
1.44  considering a new orientation, then an adaptor is worthwhile to use.
1.45  To come back to the reverse oriented graph, in this situation
1.46  \code
1.47 @@ -96,39 +98,40 @@
1.48  template class can be used. The code looks as follows
1.49  \code
1.50  ListDigraph g;
1.51 -ReverseDigraph<ListGraph> rg(g);
1.52 +ReverseDigraph<ListDigraph> rg(g);
1.53  int result = algorithm(rg);
1.54  \endcode
1.55 -After running the algorithm, the original graph \c g is untouched.
1.56 -This techniques gives rise to an elegant code, and based on stable
1.57 +During running the algorithm, the original digraph \c g is untouched.
1.58 +This techniques give rise to an elegant code, and based on stable
1.59  graph adaptors, complex algorithms can be implemented easily.
1.61 -In flow, circulation and bipartite matching problems, the residual
1.62 +In flow, circulation and matching problems, the residual
1.63  graph is of particular importance. Combining an adaptor implementing
1.64 -this, shortest path algorithms and minimum mean cycle algorithms,
1.65 +this with shortest path algorithms or minimum mean cycle algorithms,
1.66  a range of weighted and cardinality optimization algorithms can be
1.67  obtained. For other examples, the interested user is referred to the
1.68  detailed documentation of particular adaptors.
1.70  The behavior of graph adaptors can be very different. Some of them keep
1.71  capabilities of the original graph while in other cases this would be
1.72 -meaningless. This means that the concepts that they are models of depend
1.73 -on the graph adaptor, and the wrapped graph(s).
1.74 -If an arc of \c rg is deleted, this is carried out by deleting the
1.75 -corresponding arc of \c g, thus the adaptor modifies the original graph.
1.76 +meaningless. This means that the concepts that they meet depend
1.77 +on the graph adaptor, and the wrapped graph.
1.78 +For example, if an arc of a reversed digraph is deleted, this is carried
1.79 +out by deleting the corresponding arc of the original digraph, thus the
1.80 +adaptor modifies the original digraph.
1.81 +However in case of a residual digraph, this operation has no sense.
1.83 -But for a residual graph, this operation has no sense.
1.84  Let us stand one more example here to simplify your work.
1.86 +ReverseDigraph has constructor
1.87  \code
1.88  ReverseDigraph(Digraph& digraph);
1.89  \endcode
1.90 -This means that in a situation, when a <tt>const ListDigraph&</tt>
1.91 +This means that in a situation, when a <tt>const %ListDigraph&</tt>
1.92  reference to a graph is given, then it have to be instantiated with
1.93 -<tt>Digraph=const ListDigraph</tt>.
1.94 +<tt>Digraph=const %ListDigraph</tt>.
1.95  \code
1.96  int algorithm1(const ListDigraph& g) {
1.98 +  ReverseDigraph<const ListDigraph> rg(g);
1.99    return algorithm2(rg);
1.101  \endcode
2.1 --- a/lemon/adaptors.h	Fri Jan 09 12:43:52 2009 +0100
2.2 +++ b/lemon/adaptors.h	Fri Jan 09 12:54:27 2009 +0100
2.3 @@ -21,7 +21,7 @@
2.6  /// \file
2.7 -/// \brief Several graph adaptors
2.8 +/// \brief Adaptor classes for digraphs and graphs
2.9  ///
2.10  /// This file contains several useful adaptors for digraphs and graphs.
2.12 @@ -346,14 +346,22 @@
2.15    ///
2.16 -  /// \brief A digraph adaptor which reverses the orientation of the arcs.
2.17 +  /// \brief Adaptor class for reversing the orientation of the arcs in
2.18 +  /// a digraph.
2.19    ///
2.20 -  /// ReverseDigraph reverses the arcs in the adapted digraph. The
2.21 -  /// SubDigraph is conform to the \ref concepts::Digraph
2.22 -  /// "Digraph concept".
2.23 +  /// ReverseDigraph can be used for reversing the arcs in a digraph.
2.24 +  /// It conforms to the \ref concepts::Digraph "Digraph" concept.
2.25    ///
2.26 -  /// \tparam _Digraph It must be conform to the \ref concepts::Digraph
2.27 -  /// "Digraph concept". The type can be specified to be const.
2.28 +  /// The adapted digraph can also be modified through this adaptor
2.29 +  /// by adding or removing nodes or arcs, unless the \c _Digraph template
2.30 +  /// parameter is set to be \c const.
2.31 +  ///
2.32 +  /// \tparam _Digraph The type of the adapted digraph.
2.33 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept.
2.34 +  /// It can also be specified to be \c const.
2.35 +  ///
2.36 +  /// \note The \c Node and \c Arc types of this adaptor and the adapted
2.37 +  /// digraph are convertible to each other.
2.38    template<typename _Digraph>
2.39    class ReverseDigraph :
2.41 @@ -367,20 +375,23 @@
2.43      /// \brief Constructor
2.44      ///
2.45 -    /// Creates a reverse digraph adaptor for the given digraph
2.46 +    /// Creates a reverse digraph adaptor for the given digraph.
2.47      explicit ReverseDigraph(Digraph& digraph) {
2.48        Parent::setDigraph(digraph);
2.49      }
2.50    };
2.52 -  /// \brief Just gives back a reverse digraph adaptor
2.54    ///
2.55 -  /// Just gives back a reverse digraph adaptor
2.56 +  /// This function just returns a read-only \ref ReverseDigraph adaptor.
2.58 +  /// \relates ReverseDigraph
2.59    template<typename Digraph>
2.60    ReverseDigraph<const Digraph> reverseDigraph(const Digraph& digraph) {
2.61      return ReverseDigraph<const Digraph>(digraph);
2.62    }
2.64 +
2.65    template <typename _Digraph, typename _NodeFilterMap,
2.66              typename _ArcFilterMap, bool _checked = true>
2.67    class SubDigraphBase : public DigraphAdaptorBase<_Digraph> {
2.68 @@ -685,41 +696,64 @@
2.71    ///
2.72 -  /// \brief An adaptor for hiding nodes and arcs in a digraph
2.73 +  /// \brief Adaptor class for hiding nodes and arcs in a digraph
2.74    ///
2.75 -  /// SubDigraph hides nodes and arcs in a digraph. A bool node map
2.76 -  /// and a bool arc map must be specified, which define the filters
2.77 -  /// for nodes and arcs. Just the nodes and arcs with true value are
2.78 -  /// shown in the subdigraph. The SubDigraph is conform to the \ref
2.79 -  /// concepts::Digraph "Digraph concept". If the \c _checked parameter
2.80 -  /// is true, then the arcs incident to filtered nodes are also
2.81 +  /// SubDigraph can be used for hiding nodes and arcs in a digraph.
2.82 +  /// A \c bool node map and a \c bool arc map must be specified, which
2.83 +  /// define the filters for nodes and arcs.
2.84 +  /// Only the nodes and arcs with \c true filter value are
2.85 +  /// shown in the subdigraph. This adaptor conforms to the \ref
2.86 +  /// concepts::Digraph "Digraph" concept. If the \c _checked parameter
2.87 +  /// is \c true, then the arcs incident to hidden nodes are also
2.88    /// filtered out.
2.89    ///
2.90 -  /// \tparam _Digraph It must be conform to the \ref
2.91 -  /// concepts::Digraph "Digraph concept". The type can be specified
2.92 -  /// to const.
2.93 -  /// \tparam _NodeFilterMap A bool valued node map of the the adapted digraph.
2.94 -  /// \tparam _ArcFilterMap A bool valued arc map of the the adapted digraph.
2.95 -  /// \tparam _checked If the parameter is false then the arc filtering
2.96 -  /// is not checked with respect to node filter. Otherwise, each arc
2.97 -  /// is automatically filtered, which is incident to a filtered node.
2.98 +  /// The adapted digraph can also be modified through this adaptor
2.99 +  /// by adding or removing nodes or arcs, unless the \c _Digraph template
2.100 +  /// parameter is set to be \c const.
2.101 +  ///
2.102 +  /// \tparam _Digraph The type of the adapted digraph.
2.103 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept.
2.104 +  /// It can also be specified to be \c const.
2.105 +  /// \tparam _NodeFilterMap A \c bool (or convertible) node map of the
2.106 +  /// adapted digraph. The default map type is
2.107 +  /// \ref concepts::Digraph::NodeMap "_Digraph::NodeMap<bool>".
2.108 +  /// \tparam _ArcFilterMap A \c bool (or convertible) arc map of the
2.109 +  /// adapted digraph. The default map type is
2.110 +  /// \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<bool>".
2.111 +  /// \tparam _checked If this parameter is set to \c false, then the arc
2.112 +  /// filtering is not checked with respect to the node filter.
2.113 +  /// Otherwise, each arc that is incident to a hidden node is automatically
2.114 +  /// filtered out. This is the default option.
2.115 +  ///
2.116 +  /// \note The \c Node and \c Arc types of this adaptor and the adapted
2.117 +  /// digraph are convertible to each other.
2.118    ///
2.119    /// \see FilterNodes
2.120    /// \see FilterArcs
2.121 +#ifdef DOXYGEN
2.122 +  template<typename _Digraph,
2.123 +           typename _NodeFilterMap,
2.124 +           typename _ArcFilterMap,
2.125 +           bool _checked>
2.126 +#else
2.127    template<typename _Digraph,
2.128             typename _NodeFilterMap = typename _Digraph::template NodeMap<bool>,
2.129             typename _ArcFilterMap = typename _Digraph::template ArcMap<bool>,
2.130             bool _checked = true>
2.131 +#endif
2.132    class SubDigraph
2.134        SubDigraphBase<_Digraph, _NodeFilterMap, _ArcFilterMap, _checked> > {
2.135    public:
2.136 +    /// The type of the adapted digraph.
2.137      typedef _Digraph Digraph;
2.138 +    /// The type of the node filter map.
2.139      typedef _NodeFilterMap NodeFilterMap;
2.140 +    /// The type of the arc filter map.
2.141      typedef _ArcFilterMap ArcFilterMap;
2.144 -      SubDigraphBase<Digraph, NodeFilterMap, ArcFilterMap, _checked> >
2.145 +      SubDigraphBase<_Digraph, _NodeFilterMap, _ArcFilterMap, _checked> >
2.146      Parent;
2.148      typedef typename Parent::Node Node;
2.149 @@ -731,8 +765,8 @@
2.151      /// \brief Constructor
2.152      ///
2.153 -    /// Creates a subdigraph for the given digraph with
2.154 -    /// given node and arc map filters.
2.155 +    /// Creates a subdigraph for the given digraph with the
2.156 +    /// given node and arc filter maps.
2.157      SubDigraph(Digraph& digraph, NodeFilterMap& node_filter,
2.158                 ArcFilterMap& arc_filter) {
2.159        setDigraph(digraph);
2.160 @@ -740,51 +774,53 @@
2.161        setArcFilterMap(arc_filter);
2.164 -    /// \brief Hides the node of the graph
2.165 +    /// \brief Hides the given node
2.166      ///
2.167 -    /// This function hides \c n in the digraph, i.e. the iteration
2.168 -    /// jumps over it. This is done by simply setting the value of \c n
2.169 -    /// to be false in the corresponding node-map.
2.170 +    /// This function hides the given node in the subdigraph,
2.171 +    /// i.e. the iteration jumps over it.
2.172 +    /// It is done by simply setting the assigned value of \c n
2.173 +    /// to be \c false in the node filter map.
2.174      void hide(const Node& n) const { Parent::hide(n); }
2.176 -    /// \brief Hides the arc of the graph
2.177 +    /// \brief Hides the given arc
2.178      ///
2.179 -    /// This function hides \c a in the digraph, i.e. the iteration
2.180 -    /// jumps over it. This is done by simply setting the value of \c a
2.181 -    /// to be false in the corresponding arc-map.
2.182 +    /// This function hides the given arc in the subdigraph,
2.183 +    /// i.e. the iteration jumps over it.
2.184 +    /// It is done by simply setting the assigned value of \c a
2.185 +    /// to be \c false in the arc filter map.
2.186      void hide(const Arc& a) const { Parent::hide(a); }
2.188 -    /// \brief Unhides the node of the graph
2.189 +    /// \brief Shows the given node
2.190      ///
2.191 -    /// The value of \c n is set to be true in the node-map which stores
2.192 -    /// hide information. If \c n was hidden previuosly, then it is shown
2.193 -    /// again
2.194 +    /// This function shows the given node in the subdigraph.
2.195 +    /// It is done by simply setting the assigned value of \c n
2.196 +    /// to be \c true in the node filter map.
2.197      void unHide(const Node& n) const { Parent::unHide(n); }
2.199 -    /// \brief Unhides the arc of the graph
2.200 +    /// \brief Shows the given arc
2.201      ///
2.202 -    /// The value of \c a is set to be true in the arc-map which stores
2.203 -    /// hide information. If \c a was hidden previuosly, then it is shown
2.204 -    /// again
2.205 +    /// This function shows the given arc in the subdigraph.
2.206 +    /// It is done by simply setting the assigned value of \c a
2.207 +    /// to be \c true in the arc filter map.
2.208      void unHide(const Arc& a) const { Parent::unHide(a); }
2.210 -    /// \brief Returns true if \c n is hidden.
2.211 +    /// \brief Returns \c true if the given node is hidden.
2.212      ///
2.213 -    /// Returns true if \c n is hidden.
2.214 +    /// This function returns \c true if the given node is hidden.
2.215 +    bool hidden(const Node& n) const { return Parent::hidden(n); }
2.217 +    /// \brief Returns \c true if the given arc is hidden.
2.218      ///
2.219 -    bool hidden(const Node& n) const { return Parent::hidden(n); }
2.221 -    /// \brief Returns true if \c a is hidden.
2.222 -    ///
2.223 -    /// Returns true if \c a is hidden.
2.224 -    ///
2.225 +    /// This function returns \c true if the given arc is hidden.
2.226      bool hidden(const Arc& a) const { return Parent::hidden(a); }
2.228    };
2.230 -  /// \brief Just gives back a subdigraph
2.232    ///
2.233 -  /// Just gives back a subdigraph
2.234 +  /// This function just returns a read-only \ref SubDigraph adaptor.
2.236 +  /// \relates SubDigraph
2.237    template<typename Digraph, typename NodeFilterMap, typename ArcFilterMap>
2.238    SubDigraph<const Digraph, NodeFilterMap, ArcFilterMap>
2.239    subDigraph(const Digraph& digraph, NodeFilterMap& nfm, ArcFilterMap& afm) {
2.240 @@ -1249,37 +1285,65 @@
2.243    ///
2.244 -  /// \brief A graph adaptor for hiding nodes and edges in an
2.245 -  /// undirected graph.
2.246 +  /// \brief Adaptor class for hiding nodes and edges in an undirected
2.247 +  /// graph.
2.248    ///
2.249 -  /// SubGraph hides nodes and edges in a graph. A bool node map and a
2.250 -  /// bool edge map must be specified, which define the filters for
2.251 -  /// nodes and edges. Just the nodes and edges with true value are
2.252 -  /// shown in the subgraph. The SubGraph is conform to the \ref
2.253 -  /// concepts::Graph "Graph concept". If the \c _checked parameter is
2.254 -  /// true, then the edges incident to filtered nodes are also
2.255 +  /// SubGraph can be used for hiding nodes and edges in a graph.
2.256 +  /// A \c bool node map and a \c bool edge map must be specified, which
2.257 +  /// define the filters for nodes and edges.
2.258 +  /// Only the nodes and edges with \c true filter value are
2.259 +  /// shown in the subgraph. This adaptor conforms to the \ref
2.260 +  /// concepts::Graph "Graph" concept. If the \c _checked parameter is
2.261 +  /// \c true, then the edges incident to hidden nodes are also
2.262    /// filtered out.
2.263    ///
2.264 -  /// \tparam _Graph It must be conform to the \ref
2.265 -  /// concepts::Graph "Graph concept". The type can be specified
2.266 -  /// to const.
2.267 -  /// \tparam _NodeFilterMap A bool valued node map of the the adapted graph.
2.268 -  /// \tparam _EdgeFilterMap A bool valued edge map of the the adapted graph.
2.269 -  /// \tparam _checked If the parameter is false then the edge filtering
2.270 -  /// is not checked with respect to node filter. Otherwise, each edge
2.271 -  /// is automatically filtered, which is incident to a filtered node.
2.272 +  /// The adapted graph can also be modified through this adaptor
2.273 +  /// by adding or removing nodes or edges, unless the \c _Graph template
2.274 +  /// parameter is set to be \c const.
2.275 +  ///
2.276 +  /// \tparam _Graph The type of the adapted graph.
2.277 +  /// It must conform to the \ref concepts::Graph "Graph" concept.
2.278 +  /// It can also be specified to be \c const.
2.279 +  /// \tparam _NodeFilterMap A \c bool (or convertible) node map of the
2.280 +  /// adapted graph. The default map type is
2.281 +  /// \ref concepts::Graph::NodeMap "_Graph::NodeMap<bool>".
2.282 +  /// \tparam _EdgeFilterMap A \c bool (or convertible) edge map of the
2.283 +  /// adapted graph. The default map type is
2.284 +  /// \ref concepts::Graph::EdgeMap "_Graph::EdgeMap<bool>".
2.285 +  /// \tparam _checked If this parameter is set to \c false, then the edge
2.286 +  /// filtering is not checked with respect to the node filter.
2.287 +  /// Otherwise, each edge that is incident to a hidden node is automatically
2.288 +  /// filtered out. This is the default option.
2.289 +  ///
2.290 +  /// \note The \c Node, \c Edge and \c Arc types of this adaptor and the
2.291 +  /// adapted graph are convertible to each other.
2.292    ///
2.293    /// \see FilterNodes
2.294    /// \see FilterEdges
2.295 -  template<typename _Graph, typename NodeFilterMap,
2.296 -           typename EdgeFilterMap, bool _checked = true>
2.297 +#ifdef DOXYGEN
2.298 +  template<typename _Graph,
2.299 +           typename _NodeFilterMap,
2.300 +           typename _EdgeFilterMap,
2.301 +           bool _checked>
2.302 +#else
2.303 +  template<typename _Graph,
2.304 +           typename _NodeFilterMap = typename _Graph::template NodeMap<bool>,
2.305 +           typename _EdgeFilterMap = typename _Graph::template EdgeMap<bool>,
2.306 +           bool _checked = true>
2.307 +#endif
2.308    class SubGraph
2.310 -      SubGraphBase<_Graph, NodeFilterMap, EdgeFilterMap, _checked> > {
2.311 +      SubGraphBase<_Graph, _NodeFilterMap, _EdgeFilterMap, _checked> > {
2.312    public:
2.313 +    /// The type of the adapted graph.
2.314      typedef _Graph Graph;
2.315 +    /// The type of the node filter map.
2.316 +    typedef _NodeFilterMap NodeFilterMap;
2.317 +    /// The type of the edge filter map.
2.318 +    typedef _EdgeFilterMap EdgeFilterMap;
2.321 -      SubGraphBase<_Graph, NodeFilterMap, EdgeFilterMap> > Parent;
2.322 +      SubGraphBase<_Graph, _NodeFilterMap, _EdgeFilterMap, _checked> > Parent;
2.324      typedef typename Parent::Node Node;
2.325      typedef typename Parent::Edge Edge;
2.326 @@ -1290,59 +1354,61 @@
2.328      /// \brief Constructor
2.329      ///
2.330 -    /// Creates a subgraph for the given graph with given node and
2.331 -    /// edge map filters.
2.332 -    SubGraph(Graph& _graph, NodeFilterMap& node_filter_map,
2.333 +    /// Creates a subgraph for the given graph with the given node
2.334 +    /// and edge filter maps.
2.335 +    SubGraph(Graph& graph, NodeFilterMap& node_filter_map,
2.336               EdgeFilterMap& edge_filter_map) {
2.337 -      setGraph(_graph);
2.338 +      setGraph(graph);
2.339        setNodeFilterMap(node_filter_map);
2.340        setEdgeFilterMap(edge_filter_map);
2.343 -    /// \brief Hides the node of the graph
2.344 +    /// \brief Hides the given node
2.345      ///
2.346 -    /// This function hides \c n in the graph, i.e. the iteration
2.347 -    /// jumps over it. This is done by simply setting the value of \c n
2.348 -    /// to be false in the corresponding node-map.
2.349 +    /// This function hides the given node in the subgraph,
2.350 +    /// i.e. the iteration jumps over it.
2.351 +    /// It is done by simply setting the assigned value of \c n
2.352 +    /// to be \c false in the node filter map.
2.353      void hide(const Node& n) const { Parent::hide(n); }
2.355 -    /// \brief Hides the edge of the graph
2.356 +    /// \brief Hides the given edge
2.357      ///
2.358 -    /// This function hides \c e in the graph, i.e. the iteration
2.359 -    /// jumps over it. This is done by simply setting the value of \c e
2.360 -    /// to be false in the corresponding edge-map.
2.361 +    /// This function hides the given edge in the subgraph,
2.362 +    /// i.e. the iteration jumps over it.
2.363 +    /// It is done by simply setting the assigned value of \c e
2.364 +    /// to be \c false in the edge filter map.
2.365      void hide(const Edge& e) const { Parent::hide(e); }
2.367 -    /// \brief Unhides the node of the graph
2.368 +    /// \brief Shows the given node
2.369      ///
2.370 -    /// The value of \c n is set to be true in the node-map which stores
2.371 -    /// hide information. If \c n was hidden previuosly, then it is shown
2.372 -    /// again
2.373 +    /// This function shows the given node in the subgraph.
2.374 +    /// It is done by simply setting the assigned value of \c n
2.375 +    /// to be \c true in the node filter map.
2.376      void unHide(const Node& n) const { Parent::unHide(n); }
2.378 -    /// \brief Unhides the edge of the graph
2.379 +    /// \brief Shows the given edge
2.380      ///
2.381 -    /// The value of \c e is set to be true in the edge-map which stores
2.382 -    /// hide information. If \c e was hidden previuosly, then it is shown
2.383 -    /// again
2.384 +    /// This function shows the given edge in the subgraph.
2.385 +    /// It is done by simply setting the assigned value of \c e
2.386 +    /// to be \c true in the edge filter map.
2.387      void unHide(const Edge& e) const { Parent::unHide(e); }
2.389 -    /// \brief Returns true if \c n is hidden.
2.390 +    /// \brief Returns \c true if the given node is hidden.
2.391      ///
2.392 -    /// Returns true if \c n is hidden.
2.393 +    /// This function returns \c true if the given node is hidden.
2.394 +    bool hidden(const Node& n) const { return Parent::hidden(n); }
2.396 +    /// \brief Returns \c true if the given edge is hidden.
2.397      ///
2.398 -    bool hidden(const Node& n) const { return Parent::hidden(n); }
2.400 -    /// \brief Returns true if \c e is hidden.
2.401 -    ///
2.402 -    /// Returns true if \c e is hidden.
2.403 -    ///
2.404 +    /// This function returns \c true if the given edge is hidden.
2.405      bool hidden(const Edge& e) const { return Parent::hidden(e); }
2.406    };
2.408 -  /// \brief Just gives back a subgraph
2.410    ///
2.411 -  /// Just gives back a subgraph
2.412 +  /// This function just returns a read-only \ref SubGraph adaptor.
2.414 +  /// \relates SubGraph
2.415    template<typename Graph, typename NodeFilterMap, typename ArcFilterMap>
2.416    SubGraph<const Graph, NodeFilterMap, ArcFilterMap>
2.417    subGraph(const Graph& graph, NodeFilterMap& nfm, ArcFilterMap& efm) {
2.418 @@ -1373,32 +1439,42 @@
2.419        (graph, nfm, efm);
2.424    ///
2.425 -  /// \brief An adaptor for hiding nodes from a digraph or a graph.
2.426 +  /// \brief Adaptor class for hiding nodes in a digraph or a graph.
2.427    ///
2.428 -  /// FilterNodes adaptor hides nodes in a graph or a digraph. A bool
2.429 -  /// node map must be specified, which defines the filters for
2.430 -  /// nodes. Just the unfiltered nodes and the arcs or edges incident
2.431 -  /// to unfiltered nodes are shown in the subdigraph or subgraph. The
2.432 -  /// FilterNodes is conform to the \ref concepts::Digraph
2.433 -  /// "Digraph concept" or \ref concepts::Graph "Graph concept" depending
2.434 -  /// on the \c _Digraph template parameter. If the \c _checked
2.435 -  /// parameter is true, then the arc or edges incident to filtered nodes
2.436 -  /// are also filtered out.
2.437 +  /// FilterNodes adaptor can be used for hiding nodes in a digraph or a
2.438 +  /// graph. A \c bool node map must be specified, which defines the filter
2.439 +  /// for the nodes. Only the nodes with \c true filter value and the
2.440 +  /// arcs/edges incident to nodes both with \c true filter value are shown
2.441 +  /// in the subgraph. This adaptor conforms to the \ref concepts::Digraph
2.442 +  /// "Digraph" concept or the \ref concepts::Graph "Graph" concept
2.443 +  /// depending on the \c _Graph template parameter.
2.444    ///
2.445 -  /// \tparam _Digraph It must be conform to the \ref
2.446 -  /// concepts::Digraph "Digraph concept" or \ref concepts::Graph
2.447 -  /// "Graph concept". The type can be specified to be const.
2.448 -  /// \tparam _NodeFilterMap A bool valued node map of the the adapted graph.
2.449 -  /// \tparam _checked If the parameter is false then the arc or edge
2.450 -  /// filtering is not checked with respect to node filter. In this
2.451 -  /// case just isolated nodes can be filtered out from the
2.452 -  /// graph.
2.453 +  /// The adapted (di)graph can also be modified through this adaptor
2.454 +  /// by adding or removing nodes or arcs/edges, unless the \c _Graph template
2.455 +  /// parameter is set to be \c const.
2.456 +  ///
2.457 +  /// \tparam _Graph The type of the adapted digraph or graph.
2.458 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept
2.459 +  /// or the \ref concepts::Graph "Graph" concept.
2.460 +  /// It can also be specified to be \c const.
2.461 +  /// \tparam _NodeFilterMap A \c bool (or convertible) node map of the
2.462 +  /// adapted (di)graph. The default map type is
2.463 +  /// \ref concepts::Graph::NodeMap "_Graph::NodeMap<bool>".
2.464 +  /// \tparam _checked If this parameter is set to \c false then the arc/edge
2.465 +  /// filtering is not checked with respect to the node filter. In this
2.466 +  /// case only isolated nodes can be filtered out from the graph.
2.467 +  /// Otherwise, each arc/edge that is incident to a hidden node is
2.468 +  /// automatically filtered out. This is the default option.
2.469 +  ///
2.470 +  /// \note The \c Node and <tt>Arc/Edge</tt> types of this adaptor and the
2.471 +  /// adapted (di)graph are convertible to each other.
2.472  #ifdef DOXYGEN
2.473 -  template<typename _Digraph,
2.474 -           typename _NodeFilterMap = typename _Digraph::template NodeMap<bool>,
2.475 -           bool _checked = true>
2.476 +  template<typename _Graph,
2.477 +           typename _NodeFilterMap,
2.478 +           bool _checked>
2.479  #else
2.480    template<typename _Digraph,
2.481             typename _NodeFilterMap = typename _Digraph::template NodeMap<bool>,
2.482 @@ -1430,33 +1506,37 @@
2.484      /// \brief Constructor
2.485      ///
2.486 -    /// Creates an adaptor for the given digraph or graph with
2.487 +    /// Creates a subgraph for the given digraph or graph with the
2.488      /// given node filter map.
2.489 -    FilterNodes(Digraph& _digraph, NodeFilterMap& node_filter) :
2.490 +#ifdef DOXYGEN
2.491 +    FilterNodes(_Graph& graph, _NodeFilterMap& node_filter) :
2.492 +#else
2.493 +    FilterNodes(Digraph& graph, NodeFilterMap& node_filter) :
2.494 +#endif
2.495        Parent(), const_true_map(true) {
2.496 -      Parent::setDigraph(_digraph);
2.497 +      Parent::setDigraph(graph);
2.498        Parent::setNodeFilterMap(node_filter);
2.499        Parent::setArcFilterMap(const_true_map);
2.502 -    /// \brief Hides the node of the graph
2.503 +    /// \brief Hides the given node
2.504      ///
2.505 -    /// This function hides \c n in the digraph or graph, i.e. the iteration
2.506 -    /// jumps over it. This is done by simply setting the value of \c n
2.507 -    /// to be false in the corresponding node map.
2.508 +    /// This function hides the given node in the subgraph,
2.509 +    /// i.e. the iteration jumps over it.
2.510 +    /// It is done by simply setting the assigned value of \c n
2.511 +    /// to be \c false in the node filter map.
2.512      void hide(const Node& n) const { Parent::hide(n); }
2.514 -    /// \brief Unhides the node of the graph
2.515 +    /// \brief Shows the given node
2.516      ///
2.517 -    /// The value of \c n is set to be true in the node-map which stores
2.518 -    /// hide information. If \c n was hidden previuosly, then it is shown
2.519 -    /// again
2.520 +    /// This function shows the given node in the subgraph.
2.521 +    /// It is done by simply setting the assigned value of \c n
2.522 +    /// to be \c true in the node filter map.
2.523      void unHide(const Node& n) const { Parent::unHide(n); }
2.525 -    /// \brief Returns true if \c n is hidden.
2.526 +    /// \brief Returns \c true if the given node is hidden.
2.527      ///
2.528 -    /// Returns true if \c n is hidden.
2.529 -    ///
2.530 +    /// This function returns \c true if the given node is hidden.
2.531      bool hidden(const Node& n) const { return Parent::hidden(n); }
2.533    };
2.534 @@ -1496,9 +1576,11 @@
2.535    };
2.538 -  /// \brief Just gives back a FilterNodes adaptor
2.540    ///
2.541 -  /// Just gives back a FilterNodes adaptor
2.542 +  /// This function just returns a read-only \ref FilterNodes adaptor.
2.544 +  /// \relates FilterNodes
2.545    template<typename Digraph, typename NodeFilterMap>
2.546    FilterNodes<const Digraph, NodeFilterMap>
2.547    filterNodes(const Digraph& digraph, NodeFilterMap& nfm) {
2.548 @@ -1513,22 +1595,39 @@
2.551    ///
2.552 -  /// \brief An adaptor for hiding arcs from a digraph.
2.553 +  /// \brief Adaptor class for hiding arcs in a digraph.
2.554    ///
2.555 -  /// FilterArcs adaptor hides arcs in a digraph. A bool arc map must
2.556 -  /// be specified, which defines the filters for arcs. Just the
2.557 -  /// unfiltered arcs are shown in the subdigraph. The FilterArcs is
2.558 -  /// conform to the \ref concepts::Digraph "Digraph concept".
2.559 +  /// FilterArcs adaptor can be used for hiding arcs in a digraph.
2.560 +  /// A \c bool arc map must be specified, which defines the filter for
2.561 +  /// the arcs. Only the arcs with \c true filter value are shown in the
2.562 +  /// subdigraph. This adaptor conforms to the \ref concepts::Digraph
2.563 +  /// "Digraph" concept.
2.564    ///
2.565 -  /// \tparam _Digraph It must be conform to the \ref concepts::Digraph
2.566 -  /// "Digraph concept". The type can be specified to be const.
2.567 -  /// \tparam _ArcFilterMap A bool valued arc map of the the adapted
2.568 -  /// graph.
2.569 -  template<typename _Digraph, typename _ArcFilterMap>
2.570 +  /// The adapted digraph can also be modified through this adaptor
2.571 +  /// by adding or removing nodes or arcs, unless the \c _Digraph template
2.572 +  /// parameter is set to be \c const.
2.573 +  ///
2.574 +  /// \tparam _Digraph The type of the adapted digraph.
2.575 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept.
2.576 +  /// It can also be specified to be \c const.
2.577 +  /// \tparam _ArcFilterMap A \c bool (or convertible) arc map of the
2.578 +  /// adapted digraph. The default map type is
2.579 +  /// \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<bool>".
2.580 +  ///
2.581 +  /// \note The \c Node and \c Arc types of this adaptor and the adapted
2.582 +  /// digraph are convertible to each other.
2.583 +#ifdef DOXYGEN
2.584 +  template<typename _Digraph,
2.585 +           typename _ArcFilterMap>
2.586 +#else
2.587 +  template<typename _Digraph,
2.588 +           typename _ArcFilterMap = typename _Digraph::template ArcMap<bool> >
2.589 +#endif
2.590    class FilterArcs :
2.591      public SubDigraph<_Digraph, ConstMap<typename _Digraph::Node, bool>,
2.592                        _ArcFilterMap, false> {
2.593    public:
2.595      typedef _Digraph Digraph;
2.596      typedef _ArcFilterMap ArcFilterMap;
2.598 @@ -1548,8 +1647,8 @@
2.600      /// \brief Constructor
2.601      ///
2.602 -    /// Creates a FilterArcs adaptor for the given graph with
2.603 -    /// given arc map filter.
2.604 +    /// Creates a subdigraph for the given digraph with the given arc
2.605 +    /// filter map.
2.606      FilterArcs(Digraph& digraph, ArcFilterMap& arc_filter)
2.607        : Parent(), const_true_map(true) {
2.608        Parent::setDigraph(digraph);
2.609 @@ -1557,31 +1656,33 @@
2.610        Parent::setArcFilterMap(arc_filter);
2.613 -    /// \brief Hides the arc of the graph
2.614 +    /// \brief Hides the given arc
2.615      ///
2.616 -    /// This function hides \c a in the graph, i.e. the iteration
2.617 -    /// jumps over it. This is done by simply setting the value of \c a
2.618 -    /// to be false in the corresponding arc map.
2.619 +    /// This function hides the given arc in the subdigraph,
2.620 +    /// i.e. the iteration jumps over it.
2.621 +    /// It is done by simply setting the assigned value of \c a
2.622 +    /// to be \c false in the arc filter map.
2.623      void hide(const Arc& a) const { Parent::hide(a); }
2.625 -    /// \brief Unhides the arc of the graph
2.626 +    /// \brief Shows the given arc
2.627      ///
2.628 -    /// The value of \c a is set to be true in the arc-map which stores
2.629 -    /// hide information. If \c a was hidden previuosly, then it is shown
2.630 -    /// again
2.631 +    /// This function shows the given arc in the subdigraph.
2.632 +    /// It is done by simply setting the assigned value of \c a
2.633 +    /// to be \c true in the arc filter map.
2.634      void unHide(const Arc& a) const { Parent::unHide(a); }
2.636 -    /// \brief Returns true if \c a is hidden.
2.637 +    /// \brief Returns \c true if the given arc is hidden.
2.638      ///
2.639 -    /// Returns true if \c a is hidden.
2.640 -    ///
2.641 +    /// This function returns \c true if the given arc is hidden.
2.642      bool hidden(const Arc& a) const { return Parent::hidden(a); }
2.644    };
2.646 -  /// \brief Just gives back an FilterArcs adaptor
2.648    ///
2.649 -  /// Just gives back an FilterArcs adaptor
2.650 +  /// This function just returns a read-only \ref FilterArcs adaptor.
2.652 +  /// \relates FilterArcs
2.653    template<typename Digraph, typename ArcFilterMap>
2.654    FilterArcs<const Digraph, ArcFilterMap>
2.655    filterArcs(const Digraph& digraph, ArcFilterMap& afm) {
2.656 @@ -1596,18 +1697,34 @@
2.659    ///
2.660 -  /// \brief An adaptor for hiding edges from a graph.
2.661 +  /// \brief Adaptor class for hiding edges in a graph.
2.662    ///
2.663 -  /// FilterEdges adaptor hides edges in a digraph. A bool edge map must
2.664 -  /// be specified, which defines the filters for edges. Just the
2.665 -  /// unfiltered edges are shown in the subdigraph. The FilterEdges is
2.666 -  /// conform to the \ref concepts::Graph "Graph concept".
2.667 +  /// FilterEdges adaptor can be used for hiding edges in a graph.
2.668 +  /// A \c bool edge map must be specified, which defines the filter for
2.669 +  /// the edges. Only the edges with \c true filter value are shown in the
2.670 +  /// subgraph. This adaptor conforms to the \ref concepts::Graph
2.671 +  /// "Graph" concept.
2.672    ///
2.673 -  /// \tparam _Graph It must be conform to the \ref concepts::Graph
2.674 -  /// "Graph concept". The type can be specified to be const.
2.675 -  /// \tparam _EdgeFilterMap A bool valued edge map of the the adapted
2.676 -  /// graph.
2.677 -  template<typename _Graph, typename _EdgeFilterMap>
2.678 +  /// The adapted graph can also be modified through this adaptor
2.679 +  /// by adding or removing nodes or edges, unless the \c _Graph template
2.680 +  /// parameter is set to be \c const.
2.681 +  ///
2.682 +  /// \tparam _Graph The type of the adapted graph.
2.683 +  /// It must conform to the \ref concepts::Graph "Graph" concept.
2.684 +  /// It can also be specified to be \c const.
2.685 +  /// \tparam _EdgeFilterMap A \c bool (or convertible) edge map of the
2.686 +  /// adapted graph. The default map type is
2.687 +  /// \ref concepts::Graph::EdgeMap "_Graph::EdgeMap<bool>".
2.688 +  ///
2.689 +  /// \note The \c Node, \c Edge and \c Arc types of this adaptor and the
2.690 +  /// adapted graph are convertible to each other.
2.691 +#ifdef DOXYGEN
2.692 +  template<typename _Graph,
2.693 +           typename _EdgeFilterMap>
2.694 +#else
2.695 +  template<typename _Graph,
2.696 +           typename _EdgeFilterMap = typename _Graph::template EdgeMap<bool> >
2.697 +#endif
2.698    class FilterEdges :
2.699      public SubGraph<_Graph, ConstMap<typename _Graph::Node,bool>,
2.700                      _EdgeFilterMap, false> {
2.701 @@ -1628,40 +1745,42 @@
2.703      /// \brief Constructor
2.704      ///
2.705 -    /// Creates a FilterEdges adaptor for the given graph with
2.706 -    /// given edge map filters.
2.707 -    FilterEdges(Graph& _graph, EdgeFilterMap& edge_filter_map) :
2.708 +    /// Creates a subgraph for the given graph with the given edge
2.709 +    /// filter map.
2.710 +    FilterEdges(Graph& graph, EdgeFilterMap& edge_filter_map) :
2.711        Parent(), const_true_map(true) {
2.712 -      Parent::setGraph(_graph);
2.713 +      Parent::setGraph(graph);
2.714        Parent::setNodeFilterMap(const_true_map);
2.715        Parent::setEdgeFilterMap(edge_filter_map);
2.718 -    /// \brief Hides the edge of the graph
2.719 +    /// \brief Hides the given edge
2.720      ///
2.721 -    /// This function hides \c e in the graph, i.e. the iteration
2.722 -    /// jumps over it. This is done by simply setting the value of \c e
2.723 -    /// to be false in the corresponding edge-map.
2.724 +    /// This function hides the given edge in the subgraph,
2.725 +    /// i.e. the iteration jumps over it.
2.726 +    /// It is done by simply setting the assigned value of \c e
2.727 +    /// to be \c false in the edge filter map.
2.728      void hide(const Edge& e) const { Parent::hide(e); }
2.730 -    /// \brief Unhides the edge of the graph
2.731 +    /// \brief Shows the given edge
2.732      ///
2.733 -    /// The value of \c e is set to be true in the edge-map which stores
2.734 -    /// hide information. If \c e was hidden previuosly, then it is shown
2.735 -    /// again
2.736 +    /// This function shows the given edge in the subgraph.
2.737 +    /// It is done by simply setting the assigned value of \c e
2.738 +    /// to be \c true in the edge filter map.
2.739      void unHide(const Edge& e) const { Parent::unHide(e); }
2.741 -    /// \brief Returns true if \c e is hidden.
2.742 +    /// \brief Returns \c true if the given edge is hidden.
2.743      ///
2.744 -    /// Returns true if \c e is hidden.
2.745 -    ///
2.746 +    /// This function returns \c true if the given edge is hidden.
2.747      bool hidden(const Edge& e) const { return Parent::hidden(e); }
2.749    };
2.751 -  /// \brief Just gives back a FilterEdges adaptor
2.753    ///
2.754 -  /// Just gives back a FilterEdges adaptor
2.755 +  /// This function just returns a read-only \ref FilterEdges adaptor.
2.757 +  /// \relates FilterEdges
2.758    template<typename Graph, typename EdgeFilterMap>
2.759    FilterEdges<const Graph, EdgeFilterMap>
2.760    filterEdges(const Graph& graph, EdgeFilterMap& efm) {
2.761 @@ -1674,6 +1793,7 @@
2.762      return FilterEdges<const Graph, const EdgeFilterMap>(graph, efm);
2.766    template <typename _Digraph>
2.767    class UndirectorBase {
2.768    public:
2.769 @@ -1713,8 +1833,6 @@
2.771      };
2.775      void first(Node& n) const {
2.776        _digraph->first(n);
2.778 @@ -2068,16 +2186,27 @@
2.781    ///
2.782 -  /// \brief Undirect the graph
2.783 +  /// \brief Adaptor class for viewing a digraph as an undirected graph.
2.784    ///
2.785 -  /// This adaptor makes an undirected graph from a directed
2.786 -  /// graph. All arcs of the underlying digraph will be showed in the
2.787 -  /// adaptor as an edge. The Orienter adaptor is conform to the \ref
2.788 -  /// concepts::Graph "Graph concept".
2.789 +  /// Undirector adaptor can be used for viewing a digraph as an undirected
2.790 +  /// graph. All arcs of the underlying digraph are showed in the
2.791 +  /// adaptor as an edge (and also as a pair of arcs, of course).
2.792 +  /// This adaptor conforms to the \ref concepts::Graph "Graph" concept.
2.793    ///
2.794 -  /// \tparam _Digraph It must be conform to the \ref
2.795 -  /// concepts::Digraph "Digraph concept". The type can be specified
2.796 -  /// to const.
2.797 +  /// The adapted digraph can also be modified through this adaptor
2.798 +  /// by adding or removing nodes or edges, unless the \c _Digraph template
2.799 +  /// parameter is set to be \c const.
2.800 +  ///
2.801 +  /// \tparam _Digraph The type of the adapted digraph.
2.802 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept.
2.803 +  /// It can also be specified to be \c const.
2.804 +  ///
2.805 +  /// \note The \c Node type of this adaptor and the adapted digraph are
2.806 +  /// convertible to each other, moreover the \c Edge type of the adaptor
2.807 +  /// and the \c Arc type of the adapted digraph are also convertible to
2.808 +  /// each other.
2.809 +  /// (Thus the \c Arc type of the adaptor is convertible to the \c Arc type
2.810 +  /// of the adapted digraph.)
2.811    template<typename _Digraph>
2.812    class Undirector
2.813      : public GraphAdaptorExtender<UndirectorBase<_Digraph> > {
2.814 @@ -2090,15 +2219,17 @@
2.816      /// \brief Constructor
2.817      ///
2.818 -    /// Creates a undirected graph from the given digraph
2.819 +    /// Creates an undirected graph from the given digraph.
2.820      Undirector(_Digraph& digraph) {
2.821        setDigraph(digraph);
2.824 -    /// \brief ArcMap combined from two original ArcMap
2.825 +    /// \brief Arc map combined from two original arc maps
2.826      ///
2.827 -    /// This class adapts two original digraph ArcMap to
2.828 -    /// get an arc map on the undirected graph.
2.829 +    /// This map adaptor class adapts two arc maps of the underlying
2.830 +    /// digraph to get an arc map of the undirected graph.
2.831 +    /// Its value type is inherited from the first arc map type
2.832 +    /// (\c %ForwardMap).
2.833      template <typename _ForwardMap, typename _BackwardMap>
2.834      class CombinedArcMap {
2.835      public:
2.836 @@ -2108,24 +2239,21 @@
2.838        typedef typename MapTraits<ForwardMap>::ReferenceMapTag ReferenceMapTag;
2.840 +      /// The key type of the map
2.841 +      typedef typename Parent::Arc Key;
2.842 +      /// The value type of the map
2.843        typedef typename ForwardMap::Value Value;
2.844 -      typedef typename Parent::Arc Key;
2.846        typedef typename MapTraits<ForwardMap>::ReturnValue ReturnValue;
2.847        typedef typename MapTraits<ForwardMap>::ConstReturnValue ConstReturnValue;
2.848        typedef typename MapTraits<ForwardMap>::ReturnValue Reference;
2.849        typedef typename MapTraits<ForwardMap>::ConstReturnValue ConstReference;
2.851 -      /// \brief Constructor
2.852 -      ///
2.853        /// Constructor
2.854        CombinedArcMap(ForwardMap& forward, BackwardMap& backward)
2.855          : _forward(&forward), _backward(&backward) {}
2.858 -      /// \brief Sets the value associated with a key.
2.859 -      ///
2.860 -      /// Sets the value associated with a key.
2.861 +      /// Sets the value associated with the given key.
2.862        void set(const Key& e, const Value& a) {
2.863          if (Parent::direction(e)) {
2.864            _forward->set(e, a);
2.865 @@ -2134,9 +2262,7 @@
2.869 -      /// \brief Returns the value associated with a key.
2.870 -      ///
2.871 -      /// Returns the value associated with a key.
2.872 +      /// Returns the value associated with the given key.
2.873        ConstReturnValue operator[](const Key& e) const {
2.874          if (Parent::direction(e)) {
2.875            return (*_forward)[e];
2.876 @@ -2145,9 +2271,7 @@
2.880 -      /// \brief Returns the value associated with a key.
2.881 -      ///
2.882 -      /// Returns the value associated with a key.
2.883 +      /// Returns a reference to the value associated with the given key.
2.884        ReturnValue operator[](const Key& e) {
2.885          if (Parent::direction(e)) {
2.886            return (*_forward)[e];
2.887 @@ -2163,9 +2287,9 @@
2.889      };
2.891 -    /// \brief Just gives back a combined arc map
2.892 +    /// \brief Returns a combined arc map
2.893      ///
2.894 -    /// Just gives back a combined arc map
2.895 +    /// This function just returns a combined arc map.
2.896      template <typename ForwardMap, typename BackwardMap>
2.897      static CombinedArcMap<ForwardMap, BackwardMap>
2.898      combinedArcMap(ForwardMap& forward, BackwardMap& backward) {
2.899 @@ -2195,15 +2319,18 @@
2.901    };
2.903 -  /// \brief Just gives back an undirected view of the given digraph
2.905    ///
2.906 -  /// Just gives back an undirected view of the given digraph
2.907 +  /// This function just returns a read-only \ref Undirector adaptor.
2.909 +  /// \relates Undirector
2.910    template<typename Digraph>
2.911    Undirector<const Digraph>
2.912    undirector(const Digraph& digraph) {
2.913      return Undirector<const Digraph>(digraph);
2.917    template <typename _Graph, typename _DirectionMap>
2.918    class OrienterBase {
2.919    public:
2.920 @@ -2364,52 +2491,76 @@
2.923    ///
2.924 -  /// \brief Orients the edges of the graph to get a digraph
2.925 +  /// \brief Adaptor class for orienting the edges of a graph to get a digraph
2.926    ///
2.927 -  /// This adaptor orients each edge in the undirected graph. The
2.928 -  /// direction of the arcs stored in an edge node map.  The arcs can
2.929 -  /// be easily reverted by the \c reverseArc() member function in the
2.930 -  /// adaptor. The Orienter adaptor is conform to the \ref
2.931 -  /// concepts::Digraph "Digraph concept".
2.932 +  /// Orienter adaptor can be used for orienting the edges of a graph to
2.933 +  /// get a digraph. A \c bool edge map of the underlying graph must be
2.934 +  /// specified, which define the direction of the arcs in the adaptor.
2.935 +  /// The arcs can be easily reversed by the \c reverseArc() member function
2.936 +  /// of the adaptor.
2.937 +  /// This class conforms to the \ref concepts::Digraph "Digraph" concept.
2.938    ///
2.939 -  /// \tparam _Graph It must be conform to the \ref concepts::Graph
2.940 -  /// "Graph concept". The type can be specified to be const.
2.941 -  /// \tparam _DirectionMap A bool valued edge map of the the adapted
2.942 -  /// graph.
2.943 +  /// The adapted graph can also be modified through this adaptor
2.944 +  /// by adding or removing nodes or arcs, unless the \c _Graph template
2.945 +  /// parameter is set to be \c const.
2.946    ///
2.947 -  /// \sa orienter
2.948 +  /// \tparam _Graph The type of the adapted graph.
2.949 +  /// It must conform to the \ref concepts::Graph "Graph" concept.
2.950 +  /// It can also be specified to be \c const.
2.951 +  /// \tparam _DirectionMap A \c bool (or convertible) edge map of the
2.952 +  /// adapted graph. The default map type is
2.953 +  /// \ref concepts::Graph::EdgeMap "_Graph::EdgeMap<bool>".
2.954 +  ///
2.955 +  /// \note The \c Node type of this adaptor and the adapted graph are
2.956 +  /// convertible to each other, moreover the \c Arc type of the adaptor
2.957 +  /// and the \c Edge type of the adapted graph are also convertible to
2.958 +  /// each other.
2.959 +#ifdef DOXYGEN
2.960    template<typename _Graph,
2.961 -           typename DirectionMap = typename _Graph::template EdgeMap<bool> >
2.962 +           typename _DirectionMap>
2.963 +#else
2.964 +  template<typename _Graph,
2.965 +           typename _DirectionMap = typename _Graph::template EdgeMap<bool> >
2.966 +#endif
2.967    class Orienter :
2.968 -    public DigraphAdaptorExtender<OrienterBase<_Graph, DirectionMap> > {
2.969 +    public DigraphAdaptorExtender<OrienterBase<_Graph, _DirectionMap> > {
2.970    public:
2.972 +    /// The type of the adapted graph.
2.973      typedef _Graph Graph;
2.974 +    /// The type of the direction edge map.
2.975 +    typedef _DirectionMap DirectionMap;
2.978 -      OrienterBase<_Graph, DirectionMap> > Parent;
2.979 +      OrienterBase<_Graph, _DirectionMap> > Parent;
2.980      typedef typename Parent::Arc Arc;
2.981    protected:
2.982      Orienter() { }
2.983    public:
2.985 -    /// \brief Constructor of the adaptor
2.986 +    /// \brief Constructor
2.987      ///
2.988 -    /// Constructor of the adaptor
2.989 +    /// Constructor of the adaptor.
2.990      Orienter(Graph& graph, DirectionMap& direction) {
2.991        setGraph(graph);
2.992        setDirectionMap(direction);
2.995 -    /// \brief Reverse arc
2.996 +    /// \brief Reverses the given arc
2.997      ///
2.998 -    /// It reverse the given arc. It simply negate the direction in the map.
2.999 +    /// This function reverses the given arc.
2.1000 +    /// It is done by simply negate the assigned value of \c a
2.1001 +    /// in the direction map.
2.1002      void reverseArc(const Arc& a) {
2.1003        Parent::reverseArc(a);
2.1005    };
2.1007 -  /// \brief Just gives back a Orienter
2.1009    ///
2.1010 -  /// Just gives back a Orienter
2.1011 +  /// This function just returns a read-only \ref Orienter adaptor.
2.1013 +  /// \relates Orienter
2.1014    template<typename Graph, typename DirectionMap>
2.1015    Orienter<const Graph, DirectionMap>
2.1016    orienter(const Graph& graph, DirectionMap& dm) {
2.1017 @@ -2491,31 +2642,51 @@
2.1020    ///
2.1021 -  /// \brief An adaptor for composing the residual graph for directed
2.1022 +  /// \brief Adaptor class for composing the residual digraph for directed
2.1023    /// flow and circulation problems.
2.1024    ///
2.1025 -  /// An adaptor for composing the residual graph for directed flow and
2.1026 -  /// circulation problems.  Let \f$G=(V, A) \f$ be a directed graph
2.1027 -  /// and let \f$F \f$ be a number type. Let moreover \f$f,c:A\to F \f$,
2.1028 -  /// be functions on the arc-set.
2.1029 +  /// Residual can be used for composing the \e residual digraph for directed
2.1030 +  /// flow and circulation problems. Let \f$G=(V, A) \f$ be a directed graph
2.1031 +  /// and let \f$F \f$ be a number type. Let \f$flow, cap: A\to F \f$ be
2.1032 +  /// functions on the arcs.
2.1033 +  /// This adaptor implements a digraph structure with node set \f$V \f$
2.1034 +  /// and arc set \f$A_{forward}\cup A_{backward} \f$,
2.1035 +  /// where \f$A_{forward}=\{uv : uv\in A, flow(uv)<cap(uv)\} \f$ and
2.1036 +  /// \f$A_{backward}=\{vu : uv\in A, flow(uv)>0\} \f$, i.e. the so
2.1037 +  /// called residual digraph.
2.1038 +  /// When the union \f$A_{forward}\cup A_{backward} \f$ is taken,
2.1039 +  /// multiplicities are counted, i.e. the adaptor has exactly
2.1040 +  /// \f$|A_{forward}| + |A_{backward}|\f$ arcs (it may have parallel
2.1041 +  /// arcs).
2.1042 +  /// This class conforms to the \ref concepts::Digraph "Digraph" concept.
2.1043    ///
2.1044 -  /// Then Residual implements the digraph structure with
2.1045 -  /// node-set \f$V \f$ and arc-set \f$A_{forward}\cup A_{backward} \f$,
2.1046 -  /// where \f$A_{forward}=\{uv : uv\in A, f(uv)<c(uv)\} \f$ and
2.1047 -  /// \f$A_{backward}=\{vu : uv\in A, f(uv)>0\} \f$, i.e. the so
2.1048 -  /// called residual graph.  When we take the union
2.1049 -  /// \f$A_{forward}\cup A_{backward} \f$, multiplicities are counted,
2.1050 -  /// i.e.  if an arc is in both \f$A_{forward} \f$ and
2.1051 -  /// \f$A_{backward} \f$, then in the adaptor it appears in both
2.1052 -  /// orientation.
2.1053 +  /// \tparam _Digraph The type of the adapted digraph.
2.1054 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept.
2.1055 +  /// It is implicitly \c const.
2.1056 +  /// \tparam _CapacityMap An arc map of some numerical type, which defines
2.1057 +  /// the capacities in the flow problem. It is implicitly \c const.
2.1058 +  /// The default map type is
2.1059 +  /// \ref concepts::Digraph::ArcMap "_Digraph::ArcMap<int>".
2.1060 +  /// \tparam _FlowMap An arc map of some numerical type, which defines
2.1061 +  /// the flow values in the flow problem.
2.1062 +  /// The default map type is \c _CapacityMap.
2.1063 +  /// \tparam _Tolerance Tolerance type for handling inexact computation.
2.1064 +  /// The default tolerance type depends on the value type of the
2.1065 +  /// capacity map.
2.1066    ///
2.1067 -  /// \tparam _Digraph It must be conform to the \ref concepts::Digraph
2.1068 -  /// "Digraph concept". The type is implicitly const.
2.1069 -  /// \tparam _CapacityMap An arc map of some numeric type, it defines
2.1070 -  /// the capacities in the flow problem. The map is implicitly const.
2.1071 -  /// \tparam _FlowMap An arc map of some numeric type, it defines
2.1072 -  /// the capacities in the flow problem.
2.1073 -  /// \tparam _Tolerance Handler for inexact computation.
2.1074 +  /// \note This adaptor is implemented using Undirector and FilterArcs
2.1076 +  ///
2.1077 +  /// \note The \c Node type of this adaptor and the adapted digraph are
2.1078 +  /// convertible to each other, moreover the \c Arc type of the adaptor
2.1079 +  /// is convertible to the \c Arc type of the adapted digraph.
2.1080 +#ifdef DOXYGEN
2.1081 +  template<typename _Digraph,
2.1082 +           typename _CapacityMap,
2.1083 +           typename _FlowMap,
2.1084 +           typename _Tolerance>
2.1085 +  class Residual
2.1086 +#else
2.1087    template<typename _Digraph,
2.1088             typename _CapacityMap = typename _Digraph::template ArcMap<int>,
2.1089             typename _FlowMap = _CapacityMap,
2.1090 @@ -2528,11 +2699,15 @@
2.1091                                        _FlowMap, _Tolerance>,
2.1093                                         _FlowMap, _Tolerance> > >
2.1094 +#endif
2.1096    public:
2.1098 +    /// The type of the underlying digraph.
2.1099      typedef _Digraph Digraph;
2.1100 +    /// The type of the capacity map.
2.1101      typedef _CapacityMap CapacityMap;
2.1102 +    /// The type of the flow map.
2.1103      typedef _FlowMap FlowMap;
2.1104      typedef _Tolerance Tolerance;
2.1106 @@ -2564,10 +2739,10 @@
2.1108    public:
2.1110 -    /// \brief Constructor of the residual digraph.
2.1111 +    /// \brief Constructor
2.1112      ///
2.1113 -    /// Constructor of the residual graph. The parameters are the digraph,
2.1114 -    /// the flow map, the capacity map and a tolerance object.
2.1115 +    /// Constructor of the residual digraph adaptor. The parameters are the
2.1116 +    /// digraph, the capacity map, the flow map, and a tolerance object.
2.1117      Residual(const Digraph& digraph, const CapacityMap& capacity,
2.1118               FlowMap& flow, const Tolerance& tolerance = Tolerance())
2.1119        : Parent(), _capacity(&capacity), _flow(&flow), _graph(digraph),
2.1120 @@ -2581,9 +2756,9 @@
2.1122      typedef typename Parent::Arc Arc;
2.1124 -    /// \brief Gives back the residual capacity of the arc.
2.1125 +    /// \brief Returns the residual capacity of the given arc.
2.1126      ///
2.1127 -    /// Gives back the residual capacity of the arc.
2.1128 +    /// Returns the residual capacity of the given arc.
2.1129      Value residualCapacity(const Arc& a) const {
2.1130        if (Undirected::direction(a)) {
2.1131          return (*_capacity)[a] - (*_flow)[a];
2.1132 @@ -2592,11 +2767,11 @@
2.1136 -    /// \brief Augment on the given arc in the residual graph.
2.1137 +    /// \brief Augment on the given arc in the residual digraph.
2.1138      ///
2.1139 -    /// Augment on the given arc in the residual graph. It increase
2.1140 -    /// or decrease the flow on the original arc depend on the direction
2.1141 -    /// of the residual arc.
2.1142 +    /// Augment on the given arc in the residual digraph. It increases
2.1143 +    /// or decreases the flow value on the original arc according to the
2.1144 +    /// direction of the residual arc.
2.1145      void augment(const Arc& a, const Value& v) const {
2.1146        if (Undirected::direction(a)) {
2.1147          _flow->set(a, (*_flow)[a] + v);
2.1148 @@ -2605,51 +2780,56 @@
2.1152 -    /// \brief Returns the direction of the arc.
2.1153 +    /// \brief Returns \c true if the given residual arc is a forward arc.
2.1154      ///
2.1155 -    /// Returns true when the arc is same oriented as the original arc.
2.1156 +    /// Returns \c true if the given residual arc has the same orientation
2.1157 +    /// as the original arc, i.e. it is a so called forward arc.
2.1158      static bool forward(const Arc& a) {
2.1159        return Undirected::direction(a);
2.1162 -    /// \brief Returns the direction of the arc.
2.1163 +    /// \brief Returns \c true if the given residual arc is a backward arc.
2.1164      ///
2.1165 -    /// Returns true when the arc is opposite oriented as the original arc.
2.1166 +    /// Returns \c true if the given residual arc has the opposite orientation
2.1167 +    /// than the original arc, i.e. it is a so called backward arc.
2.1168      static bool backward(const Arc& a) {
2.1169        return !Undirected::direction(a);
2.1172 -    /// \brief Gives back the forward oriented residual arc.
2.1173 +    /// \brief Returns the forward oriented residual arc.
2.1174      ///
2.1175 -    /// Gives back the forward oriented residual arc.
2.1176 +    /// Returns the forward oriented residual arc related to the given
2.1177 +    /// arc of the underlying digraph.
2.1178      static Arc forward(const typename Digraph::Arc& a) {
2.1179        return Undirected::direct(a, true);
2.1182 -    /// \brief Gives back the backward oriented residual arc.
2.1183 +    /// \brief Returns the backward oriented residual arc.
2.1184      ///
2.1185 -    /// Gives back the backward oriented residual arc.
2.1186 +    /// Returns the backward oriented residual arc related to the given
2.1187 +    /// arc of the underlying digraph.
2.1188      static Arc backward(const typename Digraph::Arc& a) {
2.1189        return Undirected::direct(a, false);
2.1192      /// \brief Residual capacity map.
2.1193      ///
2.1194 -    /// In generic residual graph the residual capacity can be obtained
2.1195 -    /// as a map.
2.1196 +    /// This map adaptor class can be used for obtaining the residual
2.1197 +    /// capacities as an arc map of the residual digraph.
2.1198 +    /// Its value type is inherited from the capacity map.
2.1199      class ResidualCapacity {
2.1200      protected:
2.1202      public:
2.1203 -      /// The Key type
2.1204 +      /// The key type of the map
2.1205        typedef Arc Key;
2.1206 -      /// The Value type
2.1207 +      /// The value type of the map
2.1208        typedef typename _CapacityMap::Value Value;
2.1210        /// Constructor
2.1213 -      /// \e
2.1214 +      /// Returns the value associated with the given residual arc
2.1215        Value operator[](const Arc& a) const {
2.1218 @@ -3108,25 +3288,31 @@
2.1221    ///
2.1222 -  /// \brief Split the nodes of a directed graph
2.1223 +  /// \brief Adaptor class for splitting the nodes of a digraph.
2.1224    ///
2.1225 -  /// The SplitNodes adaptor splits each node into an in-node and an
2.1226 -  /// out-node. Formaly, the adaptor replaces each \f$u \f$ node in
2.1227 -  /// the digraph with two nodes(namely node \f$u_{in} \f$ and node
2.1228 -  /// \f$u_{out} \f$). If there is a \f$(v, u) \f$ arc in the
2.1229 -  /// original digraph the new target of the arc will be \f$u_{in} \f$
2.1230 -  /// and similarly the source of the original \f$(u, v) \f$ arc
2.1231 -  /// will be \f$u_{out} \f$.  The adaptor will add for each node in
2.1232 -  /// the original digraph an additional arc which connects
2.1233 -  /// \f$(u_{in}, u_{out}) \f$.
2.1234 +  /// SplitNodes adaptor can be used for splitting each node into an
2.1235 +  /// \e in-node and an \e out-node in a digraph. Formaly, the adaptor
2.1236 +  /// replaces each node \f$u \f$ in the digraph with two nodes,
2.1237 +  /// namely node \f$u_{in} \f$ and node \f$u_{out} \f$.
2.1238 +  /// If there is a \f$(v, u) \f$ arc in the original digraph, then the
2.1239 +  /// new target of the arc will be \f$u_{in} \f$ and similarly the
2.1240 +  /// source of each original \f$(u, v) \f$ arc will be \f$u_{out} \f$.
2.1241 +  /// The adaptor adds an additional \e bind \e arc from \f$u_{in} \f$
2.1242 +  /// to \f$u_{out} \f$ for each node \f$u \f$ of the original digraph.
2.1243    ///
2.1244 -  /// The aim of this class is to run algorithm with node costs if the
2.1245 -  /// algorithm can use directly just arc costs. In this case we should use
2.1246 -  /// a \c SplitNodes and set the node cost of the graph to the
2.1247 -  /// bind arc in the adapted graph.
2.1248 +  /// The aim of this class is running an algorithm with respect to node
2.1249 +  /// costs or capacities if the algorithm considers only arc costs or
2.1250 +  /// capacities directly.
2.1251 +  /// In this case you can use \c SplitNodes adaptor, and set the node
2.1252 +  /// costs/capacities of the original digraph to the \e bind \e arcs
2.1253 +  /// in the adaptor.
2.1254    ///
2.1255 -  /// \tparam _Digraph It must be conform to the \ref concepts::Digraph
2.1256 -  /// "Digraph concept". The type can be specified to be const.
2.1257 +  /// \tparam _Digraph The type of the adapted digraph.
2.1258 +  /// It must conform to the \ref concepts::Digraph "Digraph" concept.
2.1259 +  /// It is implicitly \c const.
2.1260 +  ///
2.1261 +  /// \note The \c Node type of this adaptor is converible to the \c Node
2.1262 +  /// type of the adapted digraph.
2.1263    template <typename _Digraph>
2.1264    class SplitNodes
2.1265      : public DigraphAdaptorExtender<SplitNodesBase<const _Digraph> > {
2.1266 @@ -3140,78 +3326,88 @@
2.1267      typedef typename Parent::Node Node;
2.1268      typedef typename Parent::Arc Arc;
2.1270 -    /// \brief Constructor of the adaptor.
2.1271 +    /// \brief Constructor
2.1272      ///
2.1273      /// Constructor of the adaptor.
2.1274      SplitNodes(const Digraph& g) {
2.1275        Parent::setDigraph(g);
2.1278 -    /// \brief Returns true when the node is in-node.
2.1279 +    /// \brief Returns \c true if the given node is an in-node.
2.1280      ///
2.1281 -    /// Returns true when the node is in-node.
2.1282 +    /// Returns \c true if the given node is an in-node.
2.1283      static bool inNode(const Node& n) {
2.1284        return Parent::inNode(n);
2.1287 -    /// \brief Returns true when the node is out-node.
2.1288 +    /// \brief Returns \c true if the given node is an out-node.
2.1289      ///
2.1290 -    /// Returns true when the node is out-node.
2.1291 +    /// Returns \c true if the given node is an out-node.
2.1292      static bool outNode(const Node& n) {
2.1293        return Parent::outNode(n);
2.1296 -    /// \brief Returns true when the arc is arc in the original digraph.
2.1297 +    /// \brief Returns \c true if the given arc is an original arc.
2.1298      ///
2.1299 -    /// Returns true when the arc is arc in the original digraph.
2.1300 +    /// Returns \c true if the given arc is one of the arcs in the
2.1301 +    /// original digraph.
2.1302      static bool origArc(const Arc& a) {
2.1303        return Parent::origArc(a);
2.1306 -    /// \brief Returns true when the arc binds an in-node and an out-node.
2.1307 +    /// \brief Returns \c true if the given arc is a bind arc.
2.1308      ///
2.1309 -    /// Returns true when the arc binds an in-node and an out-node.
2.1310 +    /// Returns \c true if the given arc is a bind arc, i.e. it connects
2.1311 +    /// an in-node and an out-node.
2.1312      static bool bindArc(const Arc& a) {
2.1313        return Parent::bindArc(a);
2.1316 -    /// \brief Gives back the in-node created from the \c node.
2.1317 +    /// \brief Returns the in-node created from the given original node.
2.1318      ///
2.1319 -    /// Gives back the in-node created from the \c node.
2.1320 +    /// Returns the in-node created from the given original node.
2.1321      static Node inNode(const DigraphNode& n) {
2.1322        return Parent::inNode(n);
2.1325 -    /// \brief Gives back the out-node created from the \c node.
2.1326 +    /// \brief Returns the out-node created from the given original node.
2.1327      ///
2.1328 -    /// Gives back the out-node created from the \c node.
2.1329 +    /// Returns the out-node created from the given original node.
2.1330      static Node outNode(const DigraphNode& n) {
2.1331        return Parent::outNode(n);
2.1334 -    /// \brief Gives back the arc binds the two part of the node.
2.1335 +    /// \brief Returns the bind arc that corresponds to the given
2.1336 +    /// original node.
2.1337      ///
2.1338 -    /// Gives back the arc binds the two part of the node.
2.1339 +    /// Returns the bind arc in the adaptor that corresponds to the given
2.1340 +    /// original node, i.e. the arc connecting the in-node and out-node
2.1341 +    /// of \c n.
2.1342      static Arc arc(const DigraphNode& n) {
2.1343        return Parent::arc(n);
2.1346 -    /// \brief Gives back the arc of the original arc.
2.1347 +    /// \brief Returns the arc that corresponds to the given original arc.
2.1348      ///
2.1349 -    /// Gives back the arc of the original arc.
2.1350 +    /// Returns the arc in the adaptor that corresponds to the given
2.1351 +    /// original arc.
2.1352      static Arc arc(const DigraphArc& a) {
2.1353        return Parent::arc(a);
2.1356 -    /// \brief NodeMap combined from two original NodeMap
2.1357 +    /// \brief Node map combined from two original node maps
2.1358      ///
2.1359 -    /// This class adapt two of the original digraph NodeMap to
2.1360 -    /// get a node map on the adapted digraph.
2.1361 +    /// This map adaptor class adapts two node maps of the original digraph
2.1362 +    /// to get a node map of the split digraph.
2.1363 +    /// Its value type is inherited from the first node map type
2.1364 +    /// (\c InNodeMap).
2.1365      template <typename InNodeMap, typename OutNodeMap>
2.1366      class CombinedNodeMap {
2.1367      public:
2.1369 +      /// The key type of the map
2.1370        typedef Node Key;
2.1371 +      /// The value type of the map
2.1372        typedef typename InNodeMap::Value Value;
2.1374        typedef typename MapTraits<InNodeMap>::ReferenceMapTag ReferenceMapTag;
2.1375 @@ -3220,15 +3416,20 @@
2.1376        typedef typename MapTraits<InNodeMap>::ReturnValue Reference;
2.1377        typedef typename MapTraits<InNodeMap>::ConstReturnValue ConstReference;
2.1379 -      /// \brief Constructor
2.1380 -      ///
2.1381 -      /// Constructor.
2.1382 +      /// Constructor
2.1383        CombinedNodeMap(InNodeMap& in_map, OutNodeMap& out_map)
2.1384          : _in_map(in_map), _out_map(out_map) {}
2.1386 -      /// \brief The subscript operator.
2.1387 -      ///
2.1388 -      /// The subscript operator.
2.1389 +      /// Returns the value associated with the given key.
2.1390 +      Value operator[](const Key& key) const {
2.1391 +        if (Parent::inNode(key)) {
2.1392 +          return _in_map[key];
2.1393 +        } else {
2.1394 +          return _out_map[key];
2.1395 +        }
2.1396 +      }
2.1398 +      /// Returns a reference to the value associated with the given key.
2.1399        Value& operator[](const Key& key) {
2.1400          if (Parent::inNode(key)) {
2.1401            return _in_map[key];
2.1402 @@ -3237,20 +3438,7 @@
2.1406 -      /// \brief The const subscript operator.
2.1407 -      ///
2.1408 -      /// The const subscript operator.
2.1409 -      Value operator[](const Key& key) const {
2.1410 -        if (Parent::inNode(key)) {
2.1411 -          return _in_map[key];
2.1412 -        } else {
2.1413 -          return _out_map[key];
2.1414 -        }
2.1415 -      }
2.1417 -      /// \brief The setter function of the map.
2.1418 -      ///
2.1419 -      /// The setter function of the map.
2.1420 +      /// Sets the value associated with the given key.
2.1421        void set(const Key& key, const Value& value) {
2.1422          if (Parent::inNode(key)) {
2.1423            _in_map.set(key, value);
2.1424 @@ -3267,9 +3455,9 @@
2.1425      };
2.1428 -    /// \brief Just gives back a combined node map
2.1429 +    /// \brief Returns a combined node map
2.1430      ///
2.1431 -    /// Just gives back a combined node map
2.1432 +    /// This function just returns a combined node map.
2.1433      template <typename InNodeMap, typename OutNodeMap>
2.1434      static CombinedNodeMap<InNodeMap, OutNodeMap>
2.1435      combinedNodeMap(InNodeMap& in_map, OutNodeMap& out_map) {
2.1436 @@ -3295,15 +3483,20 @@
2.1437          const OutNodeMap>(in_map, out_map);
2.1440 -    /// \brief ArcMap combined from an original ArcMap and a NodeMap
2.1441 +    /// \brief Arc map combined from an arc map and a node map of the
2.1442 +    /// original digraph.
2.1443      ///
2.1444 -    /// This class adapt an original ArcMap and a NodeMap to get an
2.1445 -    /// arc map on the adapted digraph
2.1446 +    /// This map adaptor class adapts an arc map and a node map of the
2.1447 +    /// original digraph to get an arc map of the split digraph.
2.1448 +    /// Its value type is inherited from the original arc map type
2.1449 +    /// (\c DigraphArcMap).
2.1450      template <typename DigraphArcMap, typename DigraphNodeMap>
2.1451      class CombinedArcMap {
2.1452      public:
2.1454 +      /// The key type of the map
2.1455        typedef Arc Key;
2.1456 +      /// The value type of the map
2.1457        typedef typename DigraphArcMap::Value Value;
2.1459        typedef typename MapTraits<DigraphArcMap>::ReferenceMapTag
2.1460 @@ -3317,15 +3510,29 @@
2.1461        typedef typename MapTraits<DigraphArcMap>::ConstReturnValue
2.1462          ConstReference;
2.1464 -      /// \brief Constructor
2.1465 -      ///
2.1466 -      /// Constructor.
2.1467 +      /// Constructor
2.1468        CombinedArcMap(DigraphArcMap& arc_map, DigraphNodeMap& node_map)
2.1469          : _arc_map(arc_map), _node_map(node_map) {}
2.1471 -      /// \brief The subscript operator.
2.1472 -      ///
2.1473 -      /// The subscript operator.
2.1474 +      /// Returns the value associated with the given key.
2.1475 +      Value operator[](const Key& arc) const {
2.1476 +        if (Parent::origArc(arc)) {
2.1477 +          return _arc_map[arc];
2.1478 +        } else {
2.1479 +          return _node_map[arc];
2.1480 +        }
2.1481 +      }
2.1483 +      /// Returns a reference to the value associated with the given key.
2.1484 +      Value& operator[](const Key& arc) {
2.1485 +        if (Parent::origArc(arc)) {
2.1486 +          return _arc_map[arc];
2.1487 +        } else {
2.1488 +          return _node_map[arc];
2.1489 +        }
2.1490 +      }
2.1492 +      /// Sets the value associated with the given key.
2.1493        void set(const Arc& arc, const Value& val) {
2.1494          if (Parent::origArc(arc)) {
2.1495            _arc_map.set(arc, val);
2.1496 @@ -3334,36 +3541,14 @@
2.1500 -      /// \brief The const subscript operator.
2.1501 -      ///
2.1502 -      /// The const subscript operator.
2.1503 -      Value operator[](const Key& arc) const {
2.1504 -        if (Parent::origArc(arc)) {
2.1505 -          return _arc_map[arc];
2.1506 -        } else {
2.1507 -          return _node_map[arc];
2.1508 -        }
2.1509 -      }
2.1511 -      /// \brief The const subscript operator.
2.1512 -      ///
2.1513 -      /// The const subscript operator.
2.1514 -      Value& operator[](const Key& arc) {
2.1515 -        if (Parent::origArc(arc)) {
2.1516 -          return _arc_map[arc];
2.1517 -        } else {
2.1518 -          return _node_map[arc];
2.1519 -        }
2.1520 -      }
2.1522      private:
2.1523        DigraphArcMap& _arc_map;
2.1524        DigraphNodeMap& _node_map;
2.1525      };
2.1527 -    /// \brief Just gives back a combined arc map
2.1528 +    /// \brief Returns a combined arc map
2.1529      ///
2.1530 -    /// Just gives back a combined arc map
2.1531 +    /// This function just returns a combined arc map.
2.1532      template <typename DigraphArcMap, typename DigraphNodeMap>
2.1533      static CombinedArcMap<DigraphArcMap, DigraphNodeMap>
2.1534      combinedArcMap(DigraphArcMap& arc_map, DigraphNodeMap& node_map) {
2.1535 @@ -3394,9 +3579,11 @@
2.1537    };
2.1539 -  /// \brief Just gives back a node splitter