lemon-0.x: comparison lemon/graph

equal deleted inserted replaced

-:5d11fe566036
+:1feb212abbf2
 ///\ingroup gutils
 ///\file
 ///\brief Graph utilities.
 ///
-///\todo Please
-///revise the documentation.
 ///
 namespace lemon {
 /// \addtogroup gutils
 /// @{
 /// \brief Function to count the items in the graph.
 ///
-/// This function counts the items in the graph.
+/// This function counts the items (nodes, edges etc) in the graph.
 /// The complexity of the function is O(n) because
 /// it iterates on all of the items.
 template <typename Graph, typename ItemIt>
 inline int countItems(const Graph& g) {
 /// \brief Function to count the undirected edges in the graph.
 ///
 /// This function counts the undirected edges in the graph.
 /// The complexity of the function is O(e) but for some
-/// graph structure it is specialized to run in O(1).
+/// graph structures it is specialized to run in O(1).
 template <typename Graph>
 inline int countUndirEdges(const Graph& g) {
 return _countUndirEdges<Graph>(g);
 }
 else ++e;
 while(e!=INVALID && g.target(e)!=v) ++e;
 return e;
 }
-/// \brief Copy the source map to the target map.
+/// \brief Copy a map.
 ///
-/// Copy the \c source map to the \c target map. It uses the given iterator
+/// Thsi function copies the \c source map to the \c target map. It uses the
-/// to iterate on the data structure and it use the \c ref mapping to
+/// given iterator to iterate on the data structure and it uses the \c ref
-/// convert the source's keys to the target's keys.
+/// mapping to convert the source's keys to the target's keys.
 template <typename Target, typename Source,
 	    typename ItemIt, typename Ref>
 void copyMap(Target& target, const Source& source,
 	       ItemIt it, const Ref& ref) {
 for (; it != INVALID; ++it) {
 target[it] = source[it];
 }
 }
-/// \brief Class to copy a graph to an other graph.
+/// \brief Class to copy a graph.
 ///
-/// Class to copy a graph to an other graph. It can be used easier
+/// Class to copy a graph to an other graph (duplicate a graph). The
-/// with the \c copyGraph() function.
+/// simplest way of using it is through the \c copyGraph() function.
 template <typename Target, typename Source>
 class GraphCopy {
 public:
 typedef typename Source::Node Node;
 typedef typename Source::NodeIt NodeIt;
 /// copyGraph(trg, src).nodeRef(nr).edgeCrossRef(ecr);
 /// \endcode
 ///
 /// After the copy the \c nr map will contain the mapping from the
 /// source graph's nodes to the target graph's nodes and the \c ecr will
-/// contain the mapping from the target graph's edge to the source's
+/// contain the mapping from the target graph's edges to the source's
 /// edges.
 template <typename Target, typename Source>
 GraphCopy<Target, Source> copyGraph(Target& target, const Source& source) {
 return GraphCopy<Target, Source>(target, source);
 }
 typedef typename Map::ConstPointer ConstPointer;
 };
 /// Provides an immutable and unique id for each item in the graph.
-/// The IdMap class provides a unique and immutable mapping for each item
+/// The IdMap class provides a unique and immutable id for each item of the
-/// in the graph.
+/// same type (e.g. node) in the graph. This id is <ul><li>\b unique:
+/// different items (nodes) get different ids <li>\b immutable: the id of an
+/// item (node) does not change (even if you delete other nodes).  </ul>
+/// Through this map you get access (i.e. can read) the inner id values of
+/// the items stored in the graph. This map can be inverted with its member
+/// class \c InverseMap.
 ///
 template <typename _Graph, typename _Item>
 class IdMap {
 public:
 typedef _Graph Graph;
 private:
 const Graph* graph;
 public:
-/// \brief The class represents the inverse of the map.
+/// \brief The class represents the inverse of its owner (IdMap).
 ///
-/// The class represents the inverse of the map.
+/// The class represents the inverse of its owner (IdMap).
 /// \see inverse()
 class InverseMap {
 public:
 typedef True NeedCopy;
 const Graph* graph;
 };
 /// \brief Gives back the inverse of the map.
 ///
-/// Gives back the inverse of the map.
+/// Gives back the inverse of the IdMap.
 InverseMap inverse() const { return InverseMap(*graph);}
 };
 /// \brief General invertable graph-map type.
-/// This type provides simple invertable map functions.
+/// This type provides simple invertable graph-maps.
 /// The InvertableMap wraps an arbitrary ReadWriteMap
 /// and if a key is set to a new value then store it
 /// in the inverse map.
 /// \param _Graph The graph type.
 /// \param _Map The map to extend with invertable functionality.
 };
 /// \brief Provides a mutable, continuous and unique descriptor for each
 /// item in the graph.
 ///
-/// The DescriptorMap class provides a mutable, continuous and immutable
+/// The DescriptorMap class provides a unique and continuous (but mutable)
-/// mapping for each item in the graph. The value for an item may mutated
+/// descriptor (id) for each item of the same type (e.g. node) in the
-/// on each operation when the an item erased or added to graph.
+/// graph. This id is <ul><li>\b unique: different items (nodes) get
+/// different ids <li>\b continuous: the range of the ids is the set of
+/// integers between 0 and \c n-1, where \c n is the number of the items of
+/// this type (e.g. nodes) (so the id of a node can change if you delete an
+/// other node, i.e. this id is mutable).  </ul> This map can be inverted
+/// with its member class \c InverseMap.
 ///
 /// \param _Graph The graph class the \c DescriptorMap belongs to.
 /// \param _Item The Item is the Key of the Map. It may be Node, Edge or
 /// UndirEdge.
 /// \param _Map A ReadWriteMap mapping from the item type to integer.
 typedef std::vector<Item> Container;
 Container invMap;
 public:
-/// \brief The inverse map type.
+/// \brief The inverse map type of DescriptorMap.
 ///
-/// The inverse map type.
+/// The inverse map type of DescriptorMap.
 class InverseMap {
 public:
 /// \brief Constructor of the InverseMap.
 ///
 /// Constructor of the InverseMap.
 const Graph& graph;
 };
 /// \brief Returns a \ref TargetMap class
 ///
-/// This function just returns an \ref TargetMap class.
+/// This function just returns a \ref TargetMap class.
 /// \relates TargetMap
 template <typename Graph>
 inline TargetMap<Graph> targetMap(const Graph& graph) {
 return TargetMap<Graph>(graph);
 }
-/// \brief Returns the "forward" directed edge view of undirected edge.
+/// \brief Returns the "forward" directed edge view of an undirected edge.
 ///
-/// Returns the "forward" directed edge view of undirected edge.
+/// Returns the "forward" directed edge view of an undirected edge.
 /// \author Balazs Dezso
 template <typename Graph>
 class ForwardMap {
 public:
 template <typename Graph>
 inline ForwardMap<Graph> forwardMap(const Graph& graph) {
 return ForwardMap<Graph>(graph);
 }
-/// \brief Returns the "backward" directed edge view of undirected edge.
+/// \brief Returns the "backward" directed edge view of an undirected edge.
 ///
-/// Returns the "backward" directed edge view of undirected edge.
+/// Returns the "backward" directed edge view of an undirected edge.
 /// \author Balazs Dezso
 template <typename Graph>
 class BackwardMap {
 public:
 typedef True NeedCopy;
 const Graph& graph;
 };
 /// \brief Returns a \ref BackwardMap class
-/// This function just returns an \ref BackwardMap class.
+/// This function just returns a \ref BackwardMap class.
 /// \relates BackwardMap
 template <typename Graph>
 inline BackwardMap<Graph> backwardMap(const Graph& graph) {
 return BackwardMap<Graph>(graph);
 }
 };
 /// \brief Map of the node in-degrees.
 ///
-/// This map returns the in-degree of a node. Ones it is constructed,
+/// This map returns the in-degree of a node. Once it is constructed,
 /// the degrees are stored in a standard NodeMap, so each query is done
-/// in constant time. On the other hand, the values updates automatically
+/// in constant time. On the other hand, the values are updated automatically
 /// whenever the graph changes.
 ///
 /// \sa OutDegMap
 template <typename _Graph>
 };
 /// \brief Map of the node out-degrees.
 ///
-/// This map returns the out-degree of a node. One it is constructed,
+/// This map returns the out-degree of a node. Once it is constructed,
 /// the degrees are stored in a standard NodeMap, so each query is done
-/// in constant time. On the other hand, the values updates automatically
+/// in constant time. On the other hand, the values are updated automatically
 /// whenever the graph changes.
 ///
 /// \sa OutDegMap
 template <typename _Graph>

changeset 1540	7d028a73d7f2
parent 1538	777834118f73
child 1547	dd57a540ff5f