# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 2009-04-15 02:04:37
# Node ID 33c6b6e755cdad0e2f3ea31ef8070c30a18ab308
# Parent  99a31b399b599c78cc46644de96c74b5a031d71f

Small doc improvements (#263)

diff --git a/lemon/bin_heap.h b/lemon/bin_heap.h
--- a/lemon/bin_heap.h
+++ b/lemon/bin_heap.h
@@ -73,9 +73,9 @@
     /// The item-int map must be initialized in such way that it assigns
     /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
     enum State {
-      IN_HEAP = 0,    ///< \e
-      PRE_HEAP = -1,  ///< \e
-      POST_HEAP = -2  ///< \e
+      IN_HEAP = 0,    ///< = 0.
+      PRE_HEAP = -1,  ///< = -1.
+      POST_HEAP = -2  ///< = -2.
     };
 
   private:
diff --git a/lemon/concepts/graph_components.h b/lemon/concepts/graph_components.h
--- a/lemon/concepts/graph_components.h
+++ b/lemon/concepts/graph_components.h
@@ -602,7 +602,7 @@
 
       typedef IterableDigraphComponent Digraph;
 
-      /// \name Base iteration
+      /// \name Base Iteration
       ///
       /// This interface provides functions for iteration on digraph items.
       ///
@@ -654,7 +654,7 @@
 
       /// @}
 
-      /// \name Class based iteration
+      /// \name Class Based Iteration
       ///
       /// This interface provides iterator classes for digraph items.
       ///
@@ -779,7 +779,7 @@
 
       typedef IterableGraphComponent Graph;
 
-      /// \name Base iteration
+      /// \name Base Iteration
       ///
       /// This interface provides functions for iteration on edges.
       ///
@@ -818,7 +818,7 @@
 
       /// @}
 
-      /// \name Class based iteration
+      /// \name Class Based Iteration
       ///
       /// This interface provides iterator classes for edges.
       ///
diff --git a/lemon/concepts/heap.h b/lemon/concepts/heap.h
--- a/lemon/concepts/heap.h
+++ b/lemon/concepts/heap.h
@@ -71,9 +71,9 @@
       /// The item-int map must be initialized in such way that it assigns
       /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
       enum State {
-        IN_HEAP = 0,    ///< The "in heap" state constant.
-        PRE_HEAP = -1,  ///< The "pre heap" state constant.
-        POST_HEAP = -2  ///< The "post heap" state constant.
+        IN_HEAP = 0,    ///< = 0. The "in heap" state constant.
+        PRE_HEAP = -1,  ///< = -1. The "pre heap" state constant.
+        POST_HEAP = -2  ///< = -2. The "post heap" state constant.
       };
 
       /// \brief The constructor.
diff --git a/lemon/dfs.h b/lemon/dfs.h
--- a/lemon/dfs.h
+++ b/lemon/dfs.h
@@ -206,7 +206,7 @@
 
     typedef Dfs Create;
 
-    ///\name Named template parameters
+    ///\name Named Template Parameters
 
     ///@{
 
diff --git a/lemon/dijkstra.h b/lemon/dijkstra.h
--- a/lemon/dijkstra.h
+++ b/lemon/dijkstra.h
@@ -286,7 +286,7 @@
 
     typedef Dijkstra Create;
 
-    ///\name Named template parameters
+    ///\name Named Template Parameters
 
     ///@{
 
diff --git a/lemon/dimacs.h b/lemon/dimacs.h
--- a/lemon/dimacs.h
+++ b/lemon/dimacs.h
@@ -37,11 +37,16 @@
   /// DIMACS file type descriptor.
   struct DimacsDescriptor
   {
-    ///File type enum
-    enum Type
-      {
-        NONE, MIN, MAX, SP, MAT
-      };
+    ///\brief DIMACS file type enum
+    ///
+    ///DIMACS file type enum.
+    enum Type {
+      NONE,  ///< Undefined type.
+      MIN,   ///< DIMACS file type for minimum cost flow problems.
+      MAX,   ///< DIMACS file type for maximum flow problems.
+      SP,    ///< DIMACS file type for shostest path problems.
+      MAT    ///< DIMACS file type for plain graphs and matching problems.
+    };
     ///The file type
     Type type;
     ///The number of nodes in the graph
@@ -49,16 +54,16 @@
     ///The number of edges in the graph
     int edgeNum;
     int lineShift;
-    /// Constructor. Sets the type to NONE.
+    ///Constructor. It sets the type to \c NONE.
     DimacsDescriptor() : type(NONE) {}
   };
 
   ///Discover the type of a DIMACS file
 
-  ///It starts seeking the beginning of the file for the problem type
-  ///and size info. The found data is returned in a special struct
-  ///that can be evaluated and passed to the appropriate reader
-  ///function.
+  ///This function starts seeking the beginning of the given file for the
+  ///problem type and size info. 
+  ///The found data is returned in a special struct that can be evaluated
+  ///and passed to the appropriate reader function.
   DimacsDescriptor dimacsType(std::istream& is)
   {
     DimacsDescriptor r;
@@ -96,8 +101,7 @@
   }
 
 
-
-  /// DIMACS minimum cost flow reader function.
+  /// \brief DIMACS minimum cost flow reader function.
   ///
   /// This function reads a minimum cost flow instance from DIMACS format,
   /// i.e. from a DIMACS file having a line starting with
@@ -253,7 +257,7 @@
     }
   }
 
-  /// DIMACS maximum flow reader function.
+  /// \brief DIMACS maximum flow reader function.
   ///
   /// This function reads a maximum flow instance from DIMACS format,
   /// i.e. from a DIMACS file having a line starting with
@@ -287,7 +291,7 @@
     _readDimacs(is,g,capacity,s,t,infty,desc);
   }
 
-  /// DIMACS shortest path reader function.
+  /// \brief DIMACS shortest path reader function.
   ///
   /// This function reads a shortest path instance from DIMACS format,
   /// i.e. from a DIMACS file having a line starting with
@@ -313,7 +317,7 @@
     _readDimacs(is, g, length, s, t, 0, desc);
   }
 
-  /// DIMACS capacitated digraph reader function.
+  /// \brief DIMACS capacitated digraph reader function.
   ///
   /// This function reads an arc capacitated digraph instance from
   /// DIMACS 'max' or 'sp' format.
@@ -359,11 +363,11 @@
     g.addArc(s,t);
   }
   
-  /// DIMACS plain (di)graph reader function.
+  /// \brief DIMACS plain (di)graph reader function.
   ///
-  /// This function reads a (di)graph without any designated nodes and
-  /// maps from DIMACS format, i.e. from DIMACS files having a line
-  /// starting with
+  /// This function reads a plain (di)graph without any designated nodes
+  /// and maps (e.g. a matching instance) from DIMACS format, i.e. from 
+  /// DIMACS files having a line starting with
   /// \code
   ///   p mat
   /// \endcode
diff --git a/lemon/graph_to_eps.h b/lemon/graph_to_eps.h
--- a/lemon/graph_to_eps.h
+++ b/lemon/graph_to_eps.h
@@ -268,22 +268,18 @@
     /// = 1
     ///\image html nodeshape_1.png
     ///\image latex nodeshape_1.eps "SQUARE shape (1)" width=2cm
-    ///
     SQUARE=1,
     /// = 2
     ///\image html nodeshape_2.png
     ///\image latex nodeshape_2.eps "DIAMOND shape (2)" width=2cm
-    ///
     DIAMOND=2,
     /// = 3
     ///\image html nodeshape_3.png
-    ///\image latex nodeshape_2.eps "MALE shape (4)" width=2cm
-    ///
+    ///\image latex nodeshape_3.eps "MALE shape (3)" width=2cm
     MALE=3,
     /// = 4
     ///\image html nodeshape_4.png
-    ///\image latex nodeshape_2.eps "FEMALE shape (4)" width=2cm
-    ///
+    ///\image latex nodeshape_4.eps "FEMALE shape (4)" width=2cm
     FEMALE=4
   };
 
diff --git a/lemon/kruskal.h b/lemon/kruskal.h
--- a/lemon/kruskal.h
+++ b/lemon/kruskal.h
@@ -248,11 +248,11 @@
 
   /// \ingroup spantree
   ///
-  /// \brief Kruskal algorithm to find a minimum cost spanning tree of
+  /// \brief Kruskal's algorithm for finding a minimum cost spanning tree of
   /// a graph.
   ///
   /// This function runs Kruskal's algorithm to find a minimum cost
-  /// spanning tree.
+  /// spanning tree of a graph.
   /// Due to some C++ hacking, it accepts various input and output types.
   ///
   /// \param g The graph the algorithm runs on.
@@ -264,17 +264,17 @@
   /// \param in This object is used to describe the arc/edge costs.
   /// It can be one of the following choices.
   /// - An STL compatible 'Forward Container' with
-  /// <tt>std::pair<GR::Arc,X></tt> or
-  /// <tt>std::pair<GR::Edge,X></tt> as its <tt>value_type</tt>, where
-  /// \c X is the type of the costs. The pairs indicates the arcs/edges
+  /// <tt>std::pair<GR::Arc,C></tt> or
+  /// <tt>std::pair<GR::Edge,C></tt> as its <tt>value_type</tt>, where
+  /// \c C is the type of the costs. The pairs indicates the arcs/edges
   /// along with the assigned cost. <em>They must be in a
   /// cost-ascending order.</em>
   /// - Any readable arc/edge map. The values of the map indicate the
   /// arc/edge costs.
   ///
   /// \retval out Here we also have a choice.
-  /// - It can be a writable \c bool arc/edge map. After running the
-  /// algorithm it will contain the found minimum cost spanning
+  /// - It can be a writable arc/edge map with \c bool value type. After
+  /// running the algorithm it will contain the found minimum cost spanning
   /// tree: the value of an arc/edge will be set to \c true if it belongs
   /// to the tree, otherwise it will be set to \c false. The value of
   /// each arc/edge will be set exactly once.
@@ -301,8 +301,8 @@
   /// forest is calculated instead of a spanning tree.
 
 #ifdef DOXYGEN
-  template <class Graph, class In, class Out>
-  Value kruskal(GR const& g, const In& in, Out& out)
+  template <typename Graph, typename In, typename Out>
+  Value kruskal(const Graph& g, const In& in, Out& out)
 #else
   template <class Graph, class In, class Out>
   inline typename _kruskal_bits::KruskalValueSelector<In>::Value
@@ -314,8 +314,6 @@
   }
 
 
-
-
   template <class Graph, class In, class Out>
   inline typename _kruskal_bits::KruskalValueSelector<In>::Value
   kruskal(const Graph& graph, const In& in, const Out& out)
diff --git a/lemon/lgf_reader.h b/lemon/lgf_reader.h
--- a/lemon/lgf_reader.h
+++ b/lemon/lgf_reader.h
@@ -593,7 +593,7 @@
 
   public:
 
-    /// \name Reading rules
+    /// \name Reading Rules
     /// @{
 
     /// \brief Node map reading rule
@@ -698,7 +698,7 @@
 
     /// @}
 
-    /// \name Select section by name
+    /// \name Select Section by Name
     /// @{
 
     /// \brief Set \c \@nodes section to be read
@@ -727,7 +727,7 @@
 
     /// @}
 
-    /// \name Using previously constructed node or arc set
+    /// \name Using Previously Constructed Node or Arc Set
     /// @{
 
     /// \brief Use previously constructed node set
@@ -1116,7 +1116,7 @@
 
   public:
 
-    /// \name Execution of the reader
+    /// \name Execution of the Reader
     /// @{
 
     /// \brief Start the batch processing
@@ -1389,7 +1389,7 @@
 
   public:
 
-    /// \name Reading rules
+    /// \name Reading Rules
     /// @{
 
     /// \brief Node map reading rule
@@ -1540,7 +1540,7 @@
 
     /// @}
 
-    /// \name Select section by name
+    /// \name Select Section by Name
     /// @{
 
     /// \brief Set \c \@nodes section to be read
@@ -1569,7 +1569,7 @@
 
     /// @}
 
-    /// \name Using previously constructed node or edge set
+    /// \name Using Previously Constructed Node or Edge Set
     /// @{
 
     /// \brief Use previously constructed node set
@@ -1959,7 +1959,7 @@
 
   public:
 
-    /// \name Execution of the reader
+    /// \name Execution of the Reader
     /// @{
 
     /// \brief Start the batch processing
@@ -2158,7 +2158,7 @@
 
   public:
 
-    /// \name Section readers
+    /// \name Section Readers
     /// @{
 
     /// \brief Add a section processor with line oriented reading
@@ -2257,7 +2257,7 @@
   public:
 
 
-    /// \name Execution of the reader
+    /// \name Execution of the Reader
     /// @{
 
     /// \brief Start the batch processing
@@ -2439,7 +2439,7 @@
   public:
 
 
-    /// \name Node sections
+    /// \name Node Sections
     /// @{
 
     /// \brief Gives back the number of node sections in the file.
@@ -2465,7 +2465,7 @@
 
     /// @}
 
-    /// \name Arc/Edge sections
+    /// \name Arc/Edge Sections
     /// @{
 
     /// \brief Gives back the number of arc/edge sections in the file.
@@ -2523,7 +2523,7 @@
 
     /// @}
 
-    /// \name Attribute sections
+    /// \name Attribute Sections
     /// @{
 
     /// \brief Gives back the number of attribute sections in the file.
@@ -2549,7 +2549,7 @@
 
     /// @}
 
-    /// \name Extra sections
+    /// \name Extra Sections
     /// @{
 
     /// \brief Gives back the number of extra sections in the file.
@@ -2625,7 +2625,7 @@
 
   public:
 
-    /// \name Execution of the contents reader
+    /// \name Execution of the Contents Reader
     /// @{
 
     /// \brief Starts the reading
diff --git a/lemon/lgf_writer.h b/lemon/lgf_writer.h
--- a/lemon/lgf_writer.h
+++ b/lemon/lgf_writer.h
@@ -538,7 +538,7 @@
 
   public:
 
-    /// \name Writing rules
+    /// \name Writing Rules
     /// @{
 
     /// \brief Node map writing rule
@@ -641,7 +641,7 @@
       return *this;
     }
 
-    /// \name Section captions
+    /// \name Section Captions
     /// @{
 
     /// \brief Add an additional caption to the \c \@nodes section
@@ -668,7 +668,7 @@
       return *this;
     }
 
-    /// \name Skipping section
+    /// \name Skipping Section
     /// @{
 
     /// \brief Skip writing the node set
@@ -885,7 +885,7 @@
 
   public:
 
-    /// \name Execution of the writer
+    /// \name Execution of the Writer
     /// @{
 
     /// \brief Start the batch processing
@@ -1106,7 +1106,7 @@
 
   public:
 
-    /// \name Writing rules
+    /// \name Writing Rules
     /// @{
 
     /// \brief Node map writing rule
@@ -1255,7 +1255,7 @@
       return *this;
     }
 
-    /// \name Section captions
+    /// \name Section Captions
     /// @{
 
     /// \brief Add an additional caption to the \c \@nodes section
@@ -1282,7 +1282,7 @@
       return *this;
     }
 
-    /// \name Skipping section
+    /// \name Skipping Section
     /// @{
 
     /// \brief Skip writing the node set
@@ -1499,7 +1499,7 @@
 
   public:
 
-    /// \name Execution of the writer
+    /// \name Execution of the Writer
     /// @{
 
     /// \brief Start the batch processing
@@ -1651,7 +1651,7 @@
 
   public:
 
-    /// \name Section writers
+    /// \name Section Writers
     /// @{
 
     /// \brief Add a section writer with line oriented writing
@@ -1718,7 +1718,7 @@
   public:
 
 
-    /// \name Execution of the writer
+    /// \name Execution of the Writer
     /// @{
 
     /// \brief Start the batch processing
diff --git a/lemon/lp_base.h b/lemon/lp_base.h
--- a/lemon/lp_base.h
+++ b/lemon/lp_base.h
@@ -52,12 +52,12 @@
 
     ///Possible outcomes of an LP solving procedure
     enum SolveExitStatus {
-      ///This means that the problem has been successfully solved: either
+      /// = 0. It means that the problem has been successfully solved: either
       ///an optimal solution has been found or infeasibility/unboundedness
       ///has been proved.
       SOLVED = 0,
-      ///Any other case (including the case when some user specified
-      ///limit has been exceeded)
+      /// = 1. Any other case (including the case when some user specified
+      ///limit has been exceeded).
       UNSOLVED = 1
     };
 
@@ -71,15 +71,15 @@
 
     ///Enum for \c messageLevel() parameter
     enum MessageLevel {
-      /// no output (default value)
+      /// No output (default value).
       MESSAGE_NOTHING,
-      /// error messages only
+      /// Error messages only.
       MESSAGE_ERROR,
-      /// warnings
+      /// Warnings.
       MESSAGE_WARNING,
-      /// normal output
+      /// Normal output.
       MESSAGE_NORMAL,
-      /// verbose output
+      /// Verbose output.
       MESSAGE_VERBOSE
     };
     
@@ -1005,7 +1005,7 @@
     ///Gives back the name of the solver.
     const char* solverName() const {return _solverName();}
 
-    ///\name Build up and modify the LP
+    ///\name Build Up and Modify the LP
 
     ///@{
 
@@ -1788,15 +1788,15 @@
 
     /// The problem types for primal and dual problems
     enum ProblemType {
-      ///Feasible solution hasn't been found (but may exist).
+      /// = 0. Feasible solution hasn't been found (but may exist).
       UNDEFINED = 0,
-      ///The problem has no feasible solution
+      /// = 1. The problem has no feasible solution.
       INFEASIBLE = 1,
-      ///Feasible solution found
+      /// = 2. Feasible solution found.
       FEASIBLE = 2,
-      ///Optimal solution exists and found
+      /// = 3. Optimal solution exists and found.
       OPTIMAL = 3,
-      ///The cost function is unbounded
+      /// = 4. The cost function is unbounded.
       UNBOUNDED = 4
     };
 
@@ -1852,7 +1852,7 @@
 
     ///@}
 
-    ///\name Obtain the solution
+    ///\name Obtain the Solution
 
     ///@{
 
@@ -1974,17 +1974,16 @@
 
     /// The problem types for MIP problems
     enum ProblemType {
-      ///Feasible solution hasn't been found (but may exist).
+      /// = 0. Feasible solution hasn't been found (but may exist).
       UNDEFINED = 0,
-      ///The problem has no feasible solution
+      /// = 1. The problem has no feasible solution.
       INFEASIBLE = 1,
-      ///Feasible solution found
+      /// = 2. Feasible solution found.
       FEASIBLE = 2,
-      ///Optimal solution exists and found
+      /// = 3. Optimal solution exists and found.
       OPTIMAL = 3,
-      ///The cost function is unbounded
-      ///
-      ///The Mip or at least the relaxed problem is unbounded
+      /// = 4. The cost function is unbounded.
+      ///The Mip or at least the relaxed problem is unbounded.
       UNBOUNDED = 4
     };
 
@@ -2006,14 +2005,14 @@
 
     ///@}
 
-    ///\name Setting column type
+    ///\name Set Column Type
     ///@{
 
     ///Possible variable (column) types (e.g. real, integer, binary etc.)
     enum ColTypes {
-      ///Continuous variable (default)
+      /// = 0. Continuous variable (default).
       REAL = 0,
-      ///Integer variable
+      /// = 1. Integer variable.
       INTEGER = 1
     };
 
@@ -2034,7 +2033,7 @@
     }
     ///@}
 
-    ///\name Obtain the solution
+    ///\name Obtain the Solution
 
     ///@{
 
diff --git a/lemon/maps.h b/lemon/maps.h
--- a/lemon/maps.h
+++ b/lemon/maps.h
@@ -2728,8 +2728,8 @@
 
   /// \brief Potential difference map
   ///
-  /// PotentialMap returns the difference between the potentials of the
-  /// source and target nodes of each arc in a digraph, i.e. it returns
+  /// PotentialDifferenceMap returns the difference between the potentials of
+  /// the source and target nodes of each arc in a digraph, i.e. it returns
   /// \code
   ///   potential[gr.target(arc)] - potential[gr.source(arc)].
   /// \endcode
diff --git a/lemon/min_cost_arborescence.h b/lemon/min_cost_arborescence.h
--- a/lemon/min_cost_arborescence.h
+++ b/lemon/min_cost_arborescence.h
@@ -90,10 +90,10 @@
 
   /// \ingroup spantree
   ///
-  /// \brief %MinCostArborescence algorithm class.
+  /// \brief Minimum Cost Arborescence algorithm class.
   ///
   /// This class provides an efficient implementation of
-  /// %MinCostArborescence algorithm. The arborescence is a tree
+  /// Minimum Cost Arborescence algorithm. The arborescence is a tree
   /// which is directed from a given source node of the digraph. One or
   /// more sources should be given for the algorithm and it will calculate
   /// the minimum cost subgraph which are union of arborescences with the
@@ -390,7 +390,7 @@
 
   public:
 
-    /// \name Named template parameters
+    /// \name Named Template Parameters
 
     /// @{
 
@@ -630,7 +630,7 @@
 
     /// @}
 
-    /// \name Execution control
+    /// \name Execution Control
     /// The simplest way to execute the algorithm is to use
     /// one of the member functions called \c run(...). \n
     /// If you need more control on the execution,
diff --git a/lemon/random.h b/lemon/random.h
--- a/lemon/random.h
+++ b/lemon/random.h
@@ -659,7 +659,7 @@
 
     /// @}
 
-    ///\name Uniform distributions
+    ///\name Uniform Distributions
     ///
     /// @{
 
@@ -762,7 +762,7 @@
 
     /// @}
 
-    ///\name Non-uniform distributions
+    ///\name Non-uniform Distributions
     ///
     ///@{
 
@@ -938,7 +938,7 @@
 
     ///@}
 
-    ///\name Two dimensional distributions
+    ///\name Two Dimensional Distributions
     ///
     ///@{
 
diff --git a/lemon/suurballe.h b/lemon/suurballe.h
--- a/lemon/suurballe.h
+++ b/lemon/suurballe.h
@@ -288,7 +288,7 @@
       return *this;
     }
 
-    /// \name Execution control
+    /// \name Execution Control
     /// The simplest way to execute the algorithm is to call the run()
     /// function.
     /// \n
diff --git a/lemon/time_measure.h b/lemon/time_measure.h
--- a/lemon/time_measure.h
+++ b/lemon/time_measure.h
@@ -287,7 +287,7 @@
     ///
     Timer(bool run=true) :_running(run) {_reset();}
 
-    ///\name Control the state of the timer
+    ///\name Control the State of the Timer
     ///Basically a Timer can be either running or stopped,
     ///but it provides a bit finer control on the execution.
     ///The \ref lemon::Timer "Timer" also counts the number of
@@ -395,7 +395,7 @@
 
     ///@}
 
-    ///\name Query Functions for the ellapsed time
+    ///\name Query Functions for the Ellapsed Time
 
     ///@{
 
diff --git a/tools/dimacs-solver.cc b/tools/dimacs-solver.cc
--- a/tools/dimacs-solver.cc
+++ b/tools/dimacs-solver.cc
@@ -23,11 +23,10 @@
 /// This program solves various problems given in DIMACS format.
 ///
 /// See
-/// \verbatim
-///  dimacs-solver --help
-/// \endverbatim
+/// \code
+///   dimacs-solver --help
+/// \endcode
 /// for more info on usage.
-///
 
 #include <iostream>
 #include <fstream>
diff --git a/tools/dimacs-to-lgf.cc b/tools/dimacs-to-lgf.cc
--- a/tools/dimacs-to-lgf.cc
+++ b/tools/dimacs-to-lgf.cc
@@ -24,11 +24,10 @@
 /// (LGF).
 ///
 /// See
-/// \verbatim
-///  dimacs-to-lgf --help
-/// \endverbatim
-/// for more info on usage.
-///
+/// \code
+///   dimacs-to-lgf --help
+/// \endcode
+/// for more info on the usage.
 
 #include <iostream>
 #include <fstream>
diff --git a/tools/lgf-gen.cc b/tools/lgf-gen.cc
--- a/tools/lgf-gen.cc
+++ b/tools/lgf-gen.cc
@@ -23,12 +23,10 @@
 /// Graph generator application for various types of plane graphs.
 ///
 /// See
-/// \verbatim
-///  lgf-gen --help
-/// \endverbatim
+/// \code
+///   lgf-gen --help
+/// \endcode
 /// for more info on the usage.
-///
-
 
 #include <algorithm>
 #include <set>