304-new-doc-impr-f47b6c94577e.patch on Ticket #304 – Attachment – LEMON

lemon/bfs.h

# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 1249209620 -7200
# Node ID f47b6c94577e4eb539cd92afaf0b0316eb1e8ad7
# Parent  257e91516e09d8d6be58236c587e3e0199770412
Small doc improvements (#304)

diff --git a/lemon/bfs.h b/lemon/bfs.h

-                      a
     ///
     ///The type of the map that stores the predecessor
     ///arcs of the shortest paths.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
     ///Instantiates a \c PredMap.
 …
     ///The type of the map that indicates which nodes are processed.
     ///The type of the map that indicates which nodes are processed.
+    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
+    ///By default it is a NullMap.
     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
     ///Instantiates a \c ProcessedMap.
 …
     ///The type of the map that indicates which nodes are reached.
     ///The type of the map that indicates which nodes are reached.
     ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     typedef typename Digraph::template NodeMap<bool> ReachedMap;
     ///Instantiates a \c ReachedMap.
 …
     ///The type of the map that stores the distances of the nodes.
     ///The type of the map that stores the distances of the nodes.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<int> DistMap;
     ///Instantiates a \c DistMap.
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c PredMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetPredMap : public Bfs< Digraph, SetPredMapTraits<T> > {
       typedef Bfs< Digraph, SetPredMapTraits<T> > Create;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c DistMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetDistMap : public Bfs< Digraph, SetDistMapTraits<T> > {
       typedef Bfs< Digraph, SetDistMapTraits<T> > Create;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c ReachedMap type.
     ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     template <class T>
     struct SetReachedMap : public Bfs< Digraph, SetReachedMapTraits<T> > {
       typedef Bfs< Digraph, SetReachedMapTraits<T> > Create;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c ProcessedMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetProcessedMap : public Bfs< Digraph, SetProcessedMapTraits<T> > {
       typedef Bfs< Digraph, SetProcessedMapTraits<T> > Create;
 …
     ///@{
     ///The shortest path to a node.
+    ///The shortest path to the given node.
     ///Returns the shortest path to a node.
+    ///Returns the shortest path to the given node from the root(s).
     ///
     ///\warning \c t should be reached from the root(s).
     ///
 …
     ///must be called before using this function.
     Path path(Node t) const { return Path(*G, *_pred, t); }
     ///The distance of a node from the root(s).
+    ///The distance of the given node from the root(s).
     ///Returns the distance of a node from the root(s).
+    ///Returns the distance of the given node from the root(s).
     ///
     ///\warning If node \c v is not reached from the root(s), then
     ///the return value of this function is undefined.
 …
     ///must be called before using this function.
     int dist(Node v) const { return (*_dist)[v]; }
+    ///Returns the 'previous arc' of the shortest path tree for a node.
+    ///\brief Returns the 'previous arc' of the shortest path tree for
+    ///the given node.
+    ///
     ///This function returns the 'previous arc' of the shortest path
     ///tree for the node \c v, i.e. it returns the last arc of a
     ///shortest path from a root to \c v. It is \c INVALID if \c v
     ///is not reached from the root(s) or if \c v is a root.
     ///
     ///The shortest path tree used here is equal to the shortest path
     ///tree used in \ref predNode().
+    ///tree used in \ref predNode() and \ref predMap().
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
     Arc predArc(Node v) const { return (*_pred)[v];}
+    ///Returns the 'previous node' of the shortest path tree for a node.
+    ///\brief Returns the 'previous node' of the shortest path tree for
+    ///the given node.
+    ///
     ///This function returns the 'previous node' of the shortest path
     ///tree for the node \c v, i.e. it returns the last but one node
     ///from a shortest path from a root to \c v. It is \c INVALID
+    ///of a shortest path from a root to \c v. It is \c INVALID
     ///if \c v is not reached from the root(s) or if \c v is a root.
     ///
     ///The shortest path tree used here is equal to the shortest path
     ///tree used in \ref predArc().
+    ///tree used in \ref predArc() and \ref predMap().
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
 …
     ///predecessor arcs.
     ///
     ///Returns a const reference to the node map that stores the predecessor
     ///arcs, which form the shortest path tree.
+    ///arcs, which form the shortest path tree (forest).
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
     const PredMap &predMap() const { return *_pred;}
     ///Checks if a node is reached from the root(s).
+    ///Checks if the given node is reached from the root(s).
     ///Returns \c true if \c v is reached from the root(s).
     ///
 …
     ///
     ///The type of the map that stores the predecessor
     ///arcs of the shortest paths.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
     ///Instantiates a PredMap.
 …
     ///The type of the map that indicates which nodes are processed.
     ///The type of the map that indicates which nodes are processed.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     ///By default it is a NullMap.
     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
     ///Instantiates a ProcessedMap.
 …
     ///The type of the map that indicates which nodes are reached.
     ///The type of the map that indicates which nodes are reached.
     ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     typedef typename Digraph::template NodeMap<bool> ReachedMap;
     ///Instantiates a ReachedMap.
 …
     ///The type of the map that stores the distances of the nodes.
     ///The type of the map that stores the distances of the nodes.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<int> DistMap;
     ///Instantiates a DistMap.
 …
     ///The type of the shortest paths.
     ///The type of the shortest paths.
     ///It must meet the \ref concepts::Path "Path" concept.
+    ///It must conform to the \ref concepts::Path "Path" concept.
     typedef lemon::Path<Digraph> Path;
   };
   /// Default traits class used by BfsWizard
+  /// To make it easier to use Bfs algorithm
+  /// we have created a wizard class.
+  /// This \ref BfsWizard class needs default traits,
+  /// as well as the \ref Bfs class.
+  /// The \ref BfsWizardBase is a class to be the default traits of the
+  /// \ref BfsWizard class.
+  /// Default traits class used by BfsWizard.
+  /// \tparam GR The type of the digraph.
   template<class GR>
   class BfsWizardBase : public BfsWizardDefaultTraits<GR>
+  {
 …
     public:
     /// Constructor.
     /// This constructor does not require parameters, therefore it initiates
+    /// This constructor does not require parameters, it initiates
     /// all of the attributes to \c 0.
     BfsWizardBase() : _g(0), _reached(0), _processed(0), _pred(0),
                       _dist(0), _path(0), _di(0) {}
 …
+  {
     typedef TR Base;
-    ///The type of the digraph the algorithm runs on.
     typedef typename TR::Digraph Digraph;
     typedef typename Digraph::Node Node;
 …
     typedef typename Digraph::Arc Arc;
     typedef typename Digraph::OutArcIt OutArcIt;
-    ///\brief The type of the map that stores the predecessor
-    ///arcs of the shortest paths.
     typedef typename TR::PredMap PredMap;
-    ///\brief The type of the map that stores the distances of the nodes.
     typedef typename TR::DistMap DistMap;
-    ///\brief The type of the map that indicates which nodes are reached.
     typedef typename TR::ReachedMap ReachedMap;
-    ///\brief The type of the map that indicates which nodes are processed.
     typedef typename TR::ProcessedMap ProcessedMap;
-    ///The type of the shortest paths
     typedef typename TR::Path Path;
   public:
 …
       static PredMap *createPredMap(const Digraph &) { return 0; };
       SetPredMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting PredMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the predecessor map.
     ///
     ///\ref named-func-param "Named parameter"
     ///for setting PredMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that stores the predecessor arcs of the nodes.
     template<class T>
     BfsWizard<SetPredMapBase<T> > predMap(const T &t)
+    {
 …
       static ReachedMap *createReachedMap(const Digraph &) { return 0; };
       SetReachedMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting ReachedMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the reached map.
     ///
     /// \ref named-func-param "Named parameter"
     ///for setting ReachedMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that indicates which nodes are reached.
     template<class T>
     BfsWizard<SetReachedMapBase<T> > reachedMap(const T &t)
+    {
 …
       static DistMap *createDistMap(const Digraph &) { return 0; };
       SetDistMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting DistMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the distance map.
     ///
+    /// \ref named-func-param "Named parameter"
+    ///for setting DistMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that stores the distances of the nodes calculated
+    ///by the algorithm.
     template<class T>
     BfsWizard<SetDistMapBase<T> > distMap(const T &t)
+    {
 …
       static ProcessedMap *createProcessedMap(const Digraph &) { return 0; };
       SetProcessedMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting ProcessedMap object.
+    ///\brief \ref named-func-param "Named parameter" for setting
+    ///the processed map.
     ///
     /// \ref named-func-param "Named parameter"
     ///for setting ProcessedMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that indicates which nodes are processed.
     template<class T>
     BfsWizard<SetProcessedMapBase<T> > processedMap(const T &t)
+    {
 …
     /// \brief The type of the map that indicates which nodes are reached.
     ///
     /// The type of the map that indicates which nodes are reached.
     /// It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    /// It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     typedef typename Digraph::template NodeMap<bool> ReachedMap;
     /// \brief Instantiates a ReachedMap.
 …
     ///@{
     /// \brief Checks if a node is reached from the root(s).
+    /// \brief Checks if the given node is reached from the root(s).
     ///
     /// Returns \c true if \c v is reached from the root(s).
     ///

lemon/dfs.h

diff --git a/lemon/dfs.h b/lemon/dfs.h

-                      a
     ///
     ///The type of the map that stores the predecessor
     ///arcs of the %DFS paths.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
     ///Instantiates a \c PredMap.
 …
     ///The type of the map that indicates which nodes are processed.
     ///The type of the map that indicates which nodes are processed.
+    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
+    ///By default it is a NullMap.
     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
     ///Instantiates a \c ProcessedMap.
 …
     ///The type of the map that indicates which nodes are reached.
     ///The type of the map that indicates which nodes are reached.
     ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     typedef typename Digraph::template NodeMap<bool> ReachedMap;
     ///Instantiates a \c ReachedMap.
 …
     ///The type of the map that stores the distances of the nodes.
     ///The type of the map that stores the distances of the nodes.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<int> DistMap;
     ///Instantiates a \c DistMap.
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c PredMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetPredMap : public Dfs<Digraph, SetPredMapTraits<T> > {
       typedef Dfs<Digraph, SetPredMapTraits<T> > Create;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c DistMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetDistMap : public Dfs< Digraph, SetDistMapTraits<T> > {
       typedef Dfs<Digraph, SetDistMapTraits<T> > Create;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c ReachedMap type.
     ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     template <class T>
     struct SetReachedMap : public Dfs< Digraph, SetReachedMapTraits<T> > {
       typedef Dfs< Digraph, SetReachedMapTraits<T> > Create;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c ProcessedMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetProcessedMap : public Dfs< Digraph, SetProcessedMapTraits<T> > {
       typedef Dfs< Digraph, SetProcessedMapTraits<T> > Create;
 …
     ///@{
     ///The DFS path to a node.
+    ///The DFS path to the given node.
     ///Returns the DFS path to a node.
+    ///Returns the DFS path to the given node from the root(s).
     ///
     ///\warning \c t should be reached from the root(s).
     ///
 …
     ///must be called before using this function.
     Path path(Node t) const { return Path(*G, *_pred, t); }
     ///The distance of a node from the root(s).
+    ///The distance of the given node from the root(s).
     ///Returns the distance of a node from the root(s).
+    ///Returns the distance of the given node from the root(s).
     ///
     ///\warning If node \c v is not reached from the root(s), then
     ///the return value of this function is undefined.
 …
     ///must be called before using this function.
     int dist(Node v) const { return (*_dist)[v]; }
     ///Returns the 'previous arc' of the %DFS tree for a node.
+    ///Returns the 'previous arc' of the %DFS tree for the given node.
     ///This function returns the 'previous arc' of the %DFS tree for the
     ///node \c v, i.e. it returns the last arc of a %DFS path from a
 …
     ///root(s) or if \c v is a root.
     ///
     ///The %DFS tree used here is equal to the %DFS tree used in
     ///\ref predNode().
+    ///\ref predNode() and \ref predMap().
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
     Arc predArc(Node v) const { return (*_pred)[v];}
     ///Returns the 'previous node' of the %DFS tree.
+    ///Returns the 'previous node' of the %DFS tree for the given node.
     ///This function returns the 'previous node' of the %DFS
     ///tree for the node \c v, i.e. it returns the last but one node
     ///from a %DFS path from a root to \c v. It is \c INVALID
+    ///of a %DFS path from a root to \c v. It is \c INVALID
     ///if \c v is not reached from the root(s) or if \c v is a root.
     ///
     ///The %DFS tree used here is equal to the %DFS tree used in
     ///\ref predArc().
+    ///\ref predArc() and \ref predMap().
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
 …
     ///predecessor arcs.
     ///
     ///Returns a const reference to the node map that stores the predecessor
     ///arcs, which form the DFS tree.
+    ///arcs, which form the DFS tree (forest).
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
     const PredMap &predMap() const { return *_pred;}
     ///Checks if a node is reached from the root(s).
+    ///Checks if the given node. node is reached from the root(s).
     ///Returns \c true if \c v is reached from the root(s).
     ///
 …
     ///
     ///The type of the map that stores the predecessor
     ///arcs of the %DFS paths.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
     ///Instantiates a PredMap.
 …
     ///The type of the map that indicates which nodes are processed.
     ///The type of the map that indicates which nodes are processed.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     ///By default it is a NullMap.
     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
     ///Instantiates a ProcessedMap.
 …
     ///The type of the map that indicates which nodes are reached.
     ///The type of the map that indicates which nodes are reached.
     ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    ///It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     typedef typename Digraph::template NodeMap<bool> ReachedMap;
     ///Instantiates a ReachedMap.
 …
     ///The type of the map that stores the distances of the nodes.
     ///The type of the map that stores the distances of the nodes.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<int> DistMap;
     ///Instantiates a DistMap.
 …
     ///The type of the DFS paths.
     ///The type of the DFS paths.
     ///It must meet the \ref concepts::Path "Path" concept.
+    ///It must conform to the \ref concepts::Path "Path" concept.
     typedef lemon::Path<Digraph> Path;
   };
   /// Default traits class used by DfsWizard
+  /// To make it easier to use Dfs algorithm
+  /// we have created a wizard class.
+  /// This \ref DfsWizard class needs default traits,
+  /// as well as the \ref Dfs class.
+  /// The \ref DfsWizardBase is a class to be the default traits of the
+  /// \ref DfsWizard class.
+  /// Default traits class used by DfsWizard.
+  /// \tparam GR The type of the digraph.
   template<class GR>
   class DfsWizardBase : public DfsWizardDefaultTraits<GR>
+  {
 …
     public:
     /// Constructor.
     /// This constructor does not require parameters, therefore it initiates
+    /// This constructor does not require parameters, it initiates
     /// all of the attributes to \c 0.
     DfsWizardBase() : _g(0), _reached(0), _processed(0), _pred(0),
                       _dist(0), _path(0), _di(0) {}
 …
+  {
     typedef TR Base;
-    ///The type of the digraph the algorithm runs on.
     typedef typename TR::Digraph Digraph;
     typedef typename Digraph::Node Node;
 …
     typedef typename Digraph::Arc Arc;
     typedef typename Digraph::OutArcIt OutArcIt;
-    ///\brief The type of the map that stores the predecessor
-    ///arcs of the DFS paths.
     typedef typename TR::PredMap PredMap;
-    ///\brief The type of the map that stores the distances of the nodes.
     typedef typename TR::DistMap DistMap;
-    ///\brief The type of the map that indicates which nodes are reached.
     typedef typename TR::ReachedMap ReachedMap;
-    ///\brief The type of the map that indicates which nodes are processed.
     typedef typename TR::ProcessedMap ProcessedMap;
-    ///The type of the DFS paths
     typedef typename TR::Path Path;
   public:
 …
       static PredMap *createPredMap(const Digraph &) { return 0; };
       SetPredMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting PredMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the predecessor map.
     ///
     ///\ref named-func-param "Named parameter"
     ///for setting PredMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that stores the predecessor arcs of the nodes.
     template<class T>
     DfsWizard<SetPredMapBase<T> > predMap(const T &t)
+    {
 …
       static ReachedMap *createReachedMap(const Digraph &) { return 0; };
       SetReachedMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting ReachedMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the reached map.
     ///
     /// \ref named-func-param "Named parameter"
     ///for setting ReachedMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that indicates which nodes are reached.
     template<class T>
     DfsWizard<SetReachedMapBase<T> > reachedMap(const T &t)
+    {
 …
       static DistMap *createDistMap(const Digraph &) { return 0; };
       SetDistMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting DistMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the distance map.
     ///
+    /// \ref named-func-param "Named parameter"
+    ///for setting DistMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that stores the distances of the nodes calculated
+    ///by the algorithm.
     template<class T>
     DfsWizard<SetDistMapBase<T> > distMap(const T &t)
+    {
 …
       static ProcessedMap *createProcessedMap(const Digraph &) { return 0; };
       SetProcessedMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting ProcessedMap object.
+    ///\brief \ref named-func-param "Named parameter" for setting
+    ///the processed map.
     ///
     /// \ref named-func-param "Named parameter"
     ///for setting ProcessedMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that indicates which nodes are processed.
     template<class T>
     DfsWizard<SetProcessedMapBase<T> > processedMap(const T &t)
+    {
 …
     /// \brief The type of the map that indicates which nodes are reached.
     ///
     /// The type of the map that indicates which nodes are reached.
     /// It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+    /// It must conform to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
     typedef typename Digraph::template NodeMap<bool> ReachedMap;
     /// \brief Instantiates a ReachedMap.
 …
     ///@{
     /// \brief Checks if a node is reached from the root(s).
+    /// \brief Checks if the given node is reached from the root(s).
     ///
     /// Returns \c true if \c v is reached from the root(s).
     ///

lemon/dijkstra.h

diff --git a/lemon/dijkstra.h b/lemon/dijkstra.h

-                      a
     ///The type of the map that stores the arc lengths.
     ///The type of the map that stores the arc lengths.
     ///It must meet the \ref concepts::ReadMap "ReadMap" concept.
+    ///It must conform to the \ref concepts::ReadMap "ReadMap" concept.
     typedef LEN LengthMap;
     ///The type of the length of the arcs.
+    ///The type of the arc lengths.
     typedef typename LEN::Value Value;
     /// Operation traits for %Dijkstra algorithm.
 …
     ///
     ///The type of the map that stores the predecessor
     ///arcs of the shortest paths.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
     ///Instantiates a \c PredMap.
 …
     ///The type of the map that indicates which nodes are processed.
     ///The type of the map that indicates which nodes are processed.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     ///By default it is a NullMap.
     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
     ///Instantiates a \c ProcessedMap.
 …
     ///The type of the map that stores the distances of the nodes.
     ///The type of the map that stores the distances of the nodes.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename LEN::Value> DistMap;
     ///Instantiates a \c DistMap.
 …
   /// \ingroup shortest_path
   ///This class provides an efficient implementation of the %Dijkstra algorithm.
   ///
+  ///The %Dijkstra algorithm solves the single-source shortest path problem
+  ///when all arc lengths are non-negative. If there are negative lengths,
+  ///the BellmanFord algorithm should be used instead.
+  ///
   ///The arc lengths are passed to the algorithm using a
   ///\ref concepts::ReadMap "ReadMap",
   ///so it is easy to change it to any kind of length.
 …
     ///The type of the digraph the algorithm runs on.
     typedef typename TR::Digraph Digraph;
     ///The type of the length of the arcs.
+    ///The type of the arc lengths.
     typedef typename TR::LengthMap::Value Value;
     ///The type of the map that stores the arc lengths.
     typedef typename TR::LengthMap LengthMap;
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c PredMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetPredMap
       : public Dijkstra< Digraph, LengthMap, SetPredMapTraits<T> > {
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c DistMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetDistMap
       : public Dijkstra< Digraph, LengthMap, SetDistMapTraits<T> > {
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c ProcessedMap type.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     template <class T>
     struct SetProcessedMap
       : public Dijkstra< Digraph, LengthMap, SetProcessedMapTraits<T> > {
 …
     ///
     ///\ref named-templ-param "Named parameter" for setting
     ///\c OperationTraits type.
+    /// For more information see \ref DijkstraDefaultOperationTraits.
     template <class T>
     struct SetOperationTraits
       : public Dijkstra<Digraph, LengthMap, SetOperationTraitsTraits<T> > {
 …
     ///\name Query Functions
     ///The results of the %Dijkstra algorithm can be obtained using these
     ///functions.\n
     ///Either \ref run(Node) "run()" or \ref start() should be called
+    ///Either \ref run(Node) "run()" or \ref init() should be called
     ///before using them.
     ///@{
     ///The shortest path to a node.
+    ///The shortest path to the given node.
     ///Returns the shortest path to a node.
+    ///Returns the shortest path to the given node from the root(s).
     ///
     ///\warning \c t should be reached from the root(s).
     ///
 …
     ///must be called before using this function.
     Path path(Node t) const { return Path(*G, *_pred, t); }
     ///The distance of a node from the root(s).
+    ///The distance of the given node from the root(s).
     ///Returns the distance of a node from the root(s).
+    ///Returns the distance of the given node from the root(s).
     ///
     ///\warning If node \c v is not reached from the root(s), then
     ///the return value of this function is undefined.
 …
     ///must be called before using this function.
     Value dist(Node v) const { return (*_dist)[v]; }
+    ///Returns the 'previous arc' of the shortest path tree for a node.
+    ///\brief Returns the 'previous arc' of the shortest path tree for
+    ///the given node.
+    ///
     ///This function returns the 'previous arc' of the shortest path
     ///tree for the node \c v, i.e. it returns the last arc of a
     ///shortest path from a root to \c v. It is \c INVALID if \c v
     ///is not reached from the root(s) or if \c v is a root.
     ///
     ///The shortest path tree used here is equal to the shortest path
     ///tree used in \ref predNode().
+    ///tree used in \ref predNode() and \ref predMap().
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
     Arc predArc(Node v) const { return (*_pred)[v]; }
+    ///Returns the 'previous node' of the shortest path tree for a node.
+    ///\brief Returns the 'previous node' of the shortest path tree for
+    ///the given node.
+    ///
     ///This function returns the 'previous node' of the shortest path
     ///tree for the node \c v, i.e. it returns the last but one node
     ///from a shortest path from a root to \c v. It is \c INVALID
+    ///of a shortest path from a root to \c v. It is \c INVALID
     ///if \c v is not reached from the root(s) or if \c v is a root.
     ///
     ///The shortest path tree used here is equal to the shortest path
     ///tree used in \ref predArc().
+    ///tree used in \ref predArc() and \ref predMap().
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
 …
     ///predecessor arcs.
     ///
     ///Returns a const reference to the node map that stores the predecessor
     ///arcs, which form the shortest path tree.
+    ///arcs, which form the shortest path tree (forest).
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
     ///must be called before using this function.
     const PredMap &predMap() const { return *_pred;}
     ///Checks if a node is reached from the root(s).
+    ///Checks if the given node is reached from the root(s).
     ///Returns \c true if \c v is reached from the root(s).
     ///
 …
     bool processed(Node v) const { return (*_heap_cross_ref)[v] ==
                                           Heap::POST_HEAP; }
     ///The current distance of a node from the root(s).
+    ///The current distance of the given node from the root(s).
     ///Returns the current distance of a node from the root(s).
+    ///Returns the current distance of the given node from the root(s).
     ///It may be decreased in the following processes.
     ///
     ///\pre Either \ref run(Node) "run()" or \ref init()
 …
     ///The type of the map that stores the arc lengths.
     ///The type of the map that stores the arc lengths.
     ///It must meet the \ref concepts::ReadMap "ReadMap" concept.
+    ///It must conform to the \ref concepts::ReadMap "ReadMap" concept.
     typedef LEN LengthMap;
     ///The type of the length of the arcs.
+    ///The type of the arc lengths.
     typedef typename LEN::Value Value;
     /// Operation traits for Dijkstra algorithm.
 …
     ///
     ///The type of the map that stores the predecessor
     ///arcs of the shortest paths.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename Digraph::Arc> PredMap;
     ///Instantiates a PredMap.
 …
     ///The type of the map that indicates which nodes are processed.
     ///The type of the map that indicates which nodes are processed.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     ///By default it is a NullMap.
     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
     ///Instantiates a ProcessedMap.
 …
     ///The type of the map that stores the distances of the nodes.
     ///The type of the map that stores the distances of the nodes.
     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
+    ///It must conform to the \ref concepts::WriteMap "WriteMap" concept.
     typedef typename Digraph::template NodeMap<typename LEN::Value> DistMap;
     ///Instantiates a DistMap.
 …
     ///The type of the shortest paths.
     ///The type of the shortest paths.
     ///It must meet the \ref concepts::Path "Path" concept.
+    ///It must conform to the \ref concepts::Path "Path" concept.
     typedef lemon::Path<Digraph> Path;
   };
   /// Default traits class used by DijkstraWizard
+  /// To make it easier to use Dijkstra algorithm
+  /// we have created a wizard class.
+  /// This \ref DijkstraWizard class needs default traits,
+  /// as well as the \ref Dijkstra class.
+  /// The \ref DijkstraWizardBase is a class to be the default traits of the
+  /// \ref DijkstraWizard class.
+  /// Default traits class used by DijkstraWizard.
+  /// \tparam GR The type of the digraph.
+  /// \tparam LEN The type of the length map.
   template<typename GR, typename LEN>
   class DijkstraWizardBase : public DijkstraWizardDefaultTraits<GR,LEN>
+  {
 …
+  {
     typedef TR Base;
-    ///The type of the digraph the algorithm runs on.
     typedef typename TR::Digraph Digraph;
     typedef typename Digraph::Node Node;
 …
     typedef typename Digraph::Arc Arc;
     typedef typename Digraph::OutArcIt OutArcIt;
-    ///The type of the map that stores the arc lengths.
     typedef typename TR::LengthMap LengthMap;
-    ///The type of the length of the arcs.
     typedef typename LengthMap::Value Value;
-    ///\brief The type of the map that stores the predecessor
-    ///arcs of the shortest paths.
     typedef typename TR::PredMap PredMap;
-    ///The type of the map that stores the distances of the nodes.
     typedef typename TR::DistMap DistMap;
-    ///The type of the map that indicates which nodes are processed.
     typedef typename TR::ProcessedMap ProcessedMap;
-    ///The type of the shortest paths
     typedef typename TR::Path Path;
-    ///The heap type used by the dijkstra algorithm.
     typedef typename TR::Heap Heap;
   public:
 …
       static PredMap *createPredMap(const Digraph &) { return 0; };
       SetPredMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting PredMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the predecessor map.
     ///
     ///\ref named-func-param "Named parameter"
     ///for setting PredMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that stores the predecessor arcs of the nodes.
     template<class T>
     DijkstraWizard<SetPredMapBase<T> > predMap(const T &t)
+    {
 …
       static DistMap *createDistMap(const Digraph &) { return 0; };
       SetDistMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting DistMap object.
+    ///\brief \ref named-templ-param "Named parameter" for setting
+    ///the distance map.
     ///
+    ///\ref named-func-param "Named parameter"
+    ///for setting DistMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that stores the distances of the nodes calculated
+    ///by the algorithm.
     template<class T>
     DijkstraWizard<SetDistMapBase<T> > distMap(const T &t)
+    {
 …
       static ProcessedMap *createProcessedMap(const Digraph &) { return 0; };
       SetProcessedMapBase(const TR &b) : TR(b) {}
     };
+    ///\brief \ref named-func-param "Named parameter"
+    ///for setting ProcessedMap object.
+    ///\brief \ref named-func-param "Named parameter" for setting
+    ///the processed map.
     ///
     /// \ref named-func-param "Named parameter"
     ///for setting ProcessedMap object.
+    ///\ref named-templ-param "Named parameter" function for setting
+    ///the map that indicates which nodes are processed.
     template<class T>
     DijkstraWizard<SetProcessedMapBase<T> > processedMap(const T &t)
+    {
 …
       typedef T Path;
       SetPathBase(const TR &b) : TR(b) {}
     };
     ///\brief \ref named-func-param "Named parameter"
     ///for getting the shortest path to the target node.
     ///

lemon/maps.h

diff --git a/lemon/maps.h b/lemon/maps.h

-                      a
   /// order of Dfs algorithm, as the following examples show.
   /// \code
   ///   std::vector<Node> v;
   ///   dfs(g,s).processedMap(loggerBoolMap(std::back_inserter(v))).run();
+  ///   dfs(g).processedMap(loggerBoolMap(std::back_inserter(v))).run(s);
   /// \endcode
   /// \code
   ///   std::vector<Node> v(countNodes(g));
   ///   dfs(g,s).processedMap(loggerBoolMap(v.begin())).run();
+  ///   dfs(g).processedMap(loggerBoolMap(v.begin())).run(s);
   /// \endcode
   ///
   /// \note The container of the iterator must contain enough space

Context Navigation

Ticket #304: 304-new-doc-impr-f47b6c94577e.patch

lemon/bfs.h

lemon/dfs.h

lemon/dijkstra.h

lemon/maps.h

Download in other formats: