Doc improvements for Path and PathDumper concepts (#331)
authorPeter Kovacs <kpeter@inf.elte.hu>
Fri, 13 Nov 2009 17:30:26 +0100
changeset 8329ae88e7c04a7
parent 797 b7e3662faf02
child 833 e20173729589
Doc improvements for Path and PathDumper concepts (#331)
lemon/concepts/path.h
     1.1 --- a/lemon/concepts/path.h	Mon Oct 05 20:21:54 2009 +0200
     1.2 +++ b/lemon/concepts/path.h	Fri Nov 13 17:30:26 2009 +0100
     1.3 @@ -18,7 +18,7 @@
     1.4  
     1.5  ///\ingroup concept
     1.6  ///\file
     1.7 -///\brief Classes for representing paths in digraphs.
     1.8 +///\brief The concept of paths
     1.9  ///
    1.10  
    1.11  #ifndef LEMON_CONCEPTS_PATH_H
    1.12 @@ -38,13 +38,22 @@
    1.13      ///
    1.14      /// A skeleton structure for representing directed paths in a
    1.15      /// digraph.
    1.16 +    /// In a sense, a path can be treated as a list of arcs.
    1.17 +    /// LEMON path types just store this list. As a consequence, they cannot
    1.18 +    /// enumerate the nodes on the path directly and a zero length path
    1.19 +    /// cannot store its source node.
    1.20 +    ///
    1.21 +    /// The arcs of a path should be stored in the order of their directions,
    1.22 +    /// i.e. the target node of each arc should be the same as the source
    1.23 +    /// node of the next arc. This consistency could be checked using
    1.24 +    /// \ref checkPath().
    1.25 +    /// The source and target nodes of a (consistent) path can be obtained
    1.26 +    /// using \ref pathSource() and \ref pathTarget().
    1.27 +    ///
    1.28 +    /// A path can be constructed from another path of any type using the
    1.29 +    /// copy constructor or the assignment operator.
    1.30 +    ///
    1.31      /// \tparam GR The digraph type in which the path is.
    1.32 -    ///
    1.33 -    /// In a sense, the path can be treated as a list of arcs. The
    1.34 -    /// lemon path type stores just this list. As a consequence it
    1.35 -    /// cannot enumerate the nodes in the path and the zero length
    1.36 -    /// paths cannot store the source.
    1.37 -    ///
    1.38      template <typename GR>
    1.39      class Path {
    1.40      public:
    1.41 @@ -59,18 +68,18 @@
    1.42        /// \brief Default constructor
    1.43        Path() {}
    1.44  
    1.45 -      /// \brief Template constructor
    1.46 +      /// \brief Template copy constructor
    1.47        template <typename CPath>
    1.48        Path(const CPath& cpath) {}
    1.49  
    1.50 -      /// \brief Template assigment
    1.51 +      /// \brief Template assigment operator
    1.52        template <typename CPath>
    1.53        Path& operator=(const CPath& cpath) {
    1.54          ignore_unused_variable_warning(cpath);
    1.55          return *this;
    1.56        }
    1.57  
    1.58 -      /// Length of the path ie. the number of arcs in the path.
    1.59 +      /// Length of the path, i.e. the number of arcs on the path.
    1.60        int length() const { return 0;}
    1.61  
    1.62        /// Returns whether the path is empty.
    1.63 @@ -79,19 +88,19 @@
    1.64        /// Resets the path to an empty path.
    1.65        void clear() {}
    1.66  
    1.67 -      /// \brief LEMON style iterator for path arcs
    1.68 +      /// \brief LEMON style iterator for enumerating the arcs of a path.
    1.69        ///
    1.70 -      /// This class is used to iterate on the arcs of the paths.
    1.71 +      /// LEMON style iterator class for enumerating the arcs of a path.
    1.72        class ArcIt {
    1.73        public:
    1.74          /// Default constructor
    1.75          ArcIt() {}
    1.76          /// Invalid constructor
    1.77          ArcIt(Invalid) {}
    1.78 -        /// Constructor for first arc
    1.79 +        /// Sets the iterator to the first arc of the given path
    1.80          ArcIt(const Path &) {}
    1.81  
    1.82 -        /// Conversion to Arc
    1.83 +        /// Conversion to \c Arc
    1.84          operator Arc() const { return INVALID; }
    1.85  
    1.86          /// Next arc
    1.87 @@ -192,24 +201,18 @@
    1.88      /// \brief A skeleton structure for path dumpers.
    1.89      ///
    1.90      /// A skeleton structure for path dumpers. The path dumpers are
    1.91 -    /// the generalization of the paths. The path dumpers can
    1.92 -    /// enumerate the arcs of the path wheter in forward or in
    1.93 -    /// backward order.  In most time these classes are not used
    1.94 -    /// directly rather it used to assign a dumped class to a real
    1.95 -    /// path type.
    1.96 +    /// the generalization of the paths, they can enumerate the arcs
    1.97 +    /// of the path either in forward or in backward order.
    1.98 +    /// These classes are typically not used directly, they are rather
    1.99 +    /// used to be assigned to a real path type.
   1.100      ///
   1.101      /// The main purpose of this concept is that the shortest path
   1.102 -    /// algorithms can enumerate easily the arcs in reverse order.
   1.103 -    /// If we would like to give back a real path from these
   1.104 -    /// algorithms then we should create a temporarly path object. In
   1.105 -    /// LEMON such algorithms gives back a path dumper what can
   1.106 -    /// assigned to a real path and the dumpers can be implemented as
   1.107 +    /// algorithms can enumerate the arcs easily in reverse order.
   1.108 +    /// In LEMON, such algorithms give back a (reverse) path dumper that
   1.109 +    /// can be assigned to a real path. The dumpers can be implemented as
   1.110      /// an adaptor class to the predecessor map.
   1.111      ///
   1.112      /// \tparam GR The digraph type in which the path is.
   1.113 -    ///
   1.114 -    /// The paths can be constructed from any path type by a
   1.115 -    /// template constructor or a template assignment operator.
   1.116      template <typename GR>
   1.117      class PathDumper {
   1.118      public:
   1.119 @@ -219,7 +222,7 @@
   1.120        /// Arc type of the underlying digraph.
   1.121        typedef typename Digraph::Arc Arc;
   1.122  
   1.123 -      /// Length of the path ie. the number of arcs in the path.
   1.124 +      /// Length of the path, i.e. the number of arcs on the path.
   1.125        int length() const { return 0;}
   1.126  
   1.127        /// Returns whether the path is empty.
   1.128 @@ -227,25 +230,24 @@
   1.129  
   1.130        /// \brief Forward or reverse dumping
   1.131        ///
   1.132 -      /// If the RevPathTag is defined and true then reverse dumping
   1.133 -      /// is provided in the path dumper. In this case instead of the
   1.134 -      /// ArcIt the RevArcIt iterator should be implemented in the
   1.135 -      /// dumper.
   1.136 +      /// If this tag is defined to be \c True, then reverse dumping
   1.137 +      /// is provided in the path dumper. In this case, \c RevArcIt
   1.138 +      /// iterator should be implemented instead of \c ArcIt iterator.
   1.139        typedef False RevPathTag;
   1.140  
   1.141 -      /// \brief LEMON style iterator for path arcs
   1.142 +      /// \brief LEMON style iterator for enumerating the arcs of a path.
   1.143        ///
   1.144 -      /// This class is used to iterate on the arcs of the paths.
   1.145 +      /// LEMON style iterator class for enumerating the arcs of a path.
   1.146        class ArcIt {
   1.147        public:
   1.148          /// Default constructor
   1.149          ArcIt() {}
   1.150          /// Invalid constructor
   1.151          ArcIt(Invalid) {}
   1.152 -        /// Constructor for first arc
   1.153 +        /// Sets the iterator to the first arc of the given path
   1.154          ArcIt(const PathDumper&) {}
   1.155  
   1.156 -        /// Conversion to Arc
   1.157 +        /// Conversion to \c Arc
   1.158          operator Arc() const { return INVALID; }
   1.159  
   1.160          /// Next arc
   1.161 @@ -260,20 +262,21 @@
   1.162  
   1.163        };
   1.164  
   1.165 -      /// \brief LEMON style iterator for path arcs
   1.166 +      /// \brief LEMON style iterator for enumerating the arcs of a path
   1.167 +      /// in reverse direction.
   1.168        ///
   1.169 -      /// This class is used to iterate on the arcs of the paths in
   1.170 -      /// reverse direction.
   1.171 +      /// LEMON style iterator class for enumerating the arcs of a path
   1.172 +      /// in reverse direction.
   1.173        class RevArcIt {
   1.174        public:
   1.175          /// Default constructor
   1.176          RevArcIt() {}
   1.177          /// Invalid constructor
   1.178          RevArcIt(Invalid) {}
   1.179 -        /// Constructor for first arc
   1.180 +        /// Sets the iterator to the last arc of the given path
   1.181          RevArcIt(const PathDumper &) {}
   1.182  
   1.183 -        /// Conversion to Arc
   1.184 +        /// Conversion to \c Arc
   1.185          operator Arc() const { return INVALID; }
   1.186  
   1.187          /// Next arc