# HG changeset patch
# User Peter Kovacs <kpeter@inf.elte.hu>
# Date 1215209667 -7200
# Node ID 7bf5f97d574f0c8fa09366a59c7c588dd2820c03
# Parent  1e6af6f0843c373a0579fc699ac4a83bb4f5948a
Doc improvements in LGF related files

diff -r 1e6af6f0843c -r 7bf5f97d574f demo/lgf_demo.cc
--- a/demo/lgf_demo.cc	Fri Jul 04 16:12:31 2008 +0200
+++ b/demo/lgf_demo.cc	Sat Jul 05 00:14:27 2008 +0200
@@ -34,8 +34,6 @@
 #include <lemon/smart_graph.h>
 #include <lemon/lgf_reader.h>
 #include <lemon/lgf_writer.h>
-#include <lemon/random.h>
-
 
 using namespace lemon;
 
@@ -44,13 +42,13 @@
   SmartDigraph::ArcMap<int> cap(g);
   SmartDigraph::Node s, t;
 
-  digraphReader("digraph.lgf", g). // read the directeg graph into g
+  digraphReader("digraph.lgf", g). // read the directed graph into g
     arcMap("capacity", cap).       // read the 'capacity' arc map into cap
     node("source", s).             // read 'source' node to s
     node("target", t).             // read 'target' node to t
     run();
 
-  std::cout << "Digraph read from 'digraph.lgf'" << std::endl;
+  std::cout << "A digraph is read from 'digraph.lgf'." << std::endl;
   std::cout << "Number of nodes: " << countNodes(g) << std::endl;
   std::cout << "Number of arcs: " << countArcs(g) << std::endl;
 
diff -r 1e6af6f0843c -r 7bf5f97d574f doc/groups.dox
--- a/doc/groups.dox	Fri Jul 04 16:12:31 2008 +0200
+++ b/doc/groups.dox	Sat Jul 05 00:14:27 2008 +0200
@@ -475,11 +475,9 @@
 /**
 @defgroup lemon_io Lemon Input-Output
 @ingroup io_group
-\brief Reading and writing LEMON format
+\brief Reading and writing \ref lgf-format "Lemon Graph Format".
 
-This group describes methods for reading and writing LEMON format. 
-You can find more about this format on the \ref graph-io-page "Graph Input-Output"
-tutorial pages.
+This group describes methods for reading and writing \ref lgf-format "Lemon Graph Format".
 */
 
 /**
diff -r 1e6af6f0843c -r 7bf5f97d574f doc/lgf.dox
--- a/doc/lgf.dox	Fri Jul 04 16:12:31 2008 +0200
+++ b/doc/lgf.dox	Sat Jul 05 00:14:27 2008 +0200
@@ -46,7 +46,7 @@
 contain whitespaces and escape sequences. 
 
 The \c \@nodes section describes a set of nodes and associated
-maps. The first is a header line, it columns are the names of the
+maps. The first is a header line, its columns are the names of the
 maps appearing in the following lines.
 One of the maps must be called \c
 "label", which plays special role in the file.
@@ -64,7 +64,7 @@
 \endcode
 
 The \c \@arcs section is very similar to the \c \@nodes section,
-it again starts with a header line describing the names of the arc,
+it again starts with a header line describing the names of the maps,
 but the \c "label" map is not obligatory here. The following lines
 describe the arcs. The first two tokens of each line are
 the source and the target node of the arc, respectively, then come the map
diff -r 1e6af6f0843c -r 7bf5f97d574f lemon/lgf_reader.h
--- a/lemon/lgf_reader.h	Fri Jul 04 16:12:31 2008 +0200
+++ b/lemon/lgf_reader.h	Sat Jul 05 00:14:27 2008 +0200
@@ -18,7 +18,7 @@
 
 ///\ingroup lemon_io
 ///\file
-///\brief Lemon Graph Format reader.
+///\brief \ref lgf-format "Lemon Graph Format" reader.
 
 
 #ifndef LEMON_LGF_READER_H
@@ -400,7 +400,7 @@
 
   /// \ingroup lemon_io
   ///  
-  /// \brief LGF reader for directed graphs
+  /// \brief \ref lgf-format "LGF" reader for directed graphs
   ///
   /// This utility reads an \ref lgf-format "LGF" file.
   ///
@@ -410,22 +410,22 @@
   /// member function. A map reading rule can be added to the reader
   /// with the \c nodeMap() or \c arcMap() members. An optional
   /// converter parameter can also be added as a standard functor
-  /// converting from std::string to the value type of the map. If it
+  /// converting from \c std::string to the value type of the map. If it
   /// is set, it will determine how the tokens in the file should be
-  /// is converted to the map's value type. If the functor is not set,
+  /// converted to the value type of the map. If the functor is not set,
   /// then a default conversion will be used. One map can be read into
   /// multiple map objects at the same time. The \c attribute(), \c
   /// node() and \c arc() functions are used to add attribute reading
   /// rules.
   ///
   ///\code
-  ///     DigraphReader<Digraph>(std::cin, digraph).
-  ///       nodeMap("coordinates", coord_map).
-  ///       arcMap("capacity", cap_map).
-  ///       node("source", src).
-  ///       node("target", trg).
-  ///       attribute("caption", caption).
-  ///       run();
+  /// DigraphReader<Digraph>(std::cin, digraph).
+  ///   nodeMap("coordinates", coord_map).
+  ///   arcMap("capacity", cap_map).
+  ///   node("source", src).
+  ///   node("target", trg).
+  ///   attribute("caption", caption).
+  ///   run();
   ///\endcode
   ///
   /// By default the reader uses the first section in the file of the
@@ -437,14 +437,14 @@
   /// that the nodes or arcs should not be constructed (added to the
   /// graph) during the reading, but instead the label map of the items
   /// are given as a parameter of these functions. An
-  /// application of these function is multipass reading, which is
-  /// important if two \e \@arcs sections must be read from the
-  /// file. In this example the first phase would read the node set and one
+  /// application of these functions is multipass reading, which is
+  /// important if two \c \@arcs sections must be read from the
+  /// file. In this case the first phase would read the node set and one
   /// of the arc sets, while the second phase would read the second arc
   /// set into an \e ArcSet class (\c SmartArcSet or \c ListArcSet).
   /// The previously read label node map should be passed to the \c
   /// useNodes() functions. Another application of multipass reading when
-  /// paths are given as a node map or an arc map. It is impossible read this in
+  /// paths are given as a node map or an arc map. It is impossible to read this in
   /// a single pass, because the arcs are not constructed when the node
   /// maps are read.
   template <typename _Digraph>
@@ -735,7 +735,7 @@
     ///
     /// Use previously constructed node set, and specify the node
     /// label map and a functor which converts the label map values to
-    /// std::string.
+    /// \c std::string.
     template <typename Map, typename Converter>
     DigraphReader& useNodes(const Map& map, 
 			    const Converter& converter = Converter()) {
@@ -768,7 +768,7 @@
     ///
     /// Use previously constructed arc set, and specify the arc
     /// label map and a functor which converts the label map values to
-    /// std::string.
+    /// \c std::string.
     template <typename Map, typename Converter>
     DigraphReader& useArcs(const Map& map, 
 			   const Converter& converter = Converter()) {
@@ -784,12 +784,11 @@
     /// \brief Skips the reading of node section
     ///
     /// Omit the reading of the node section. This implies that each node
-    /// map reading rule will be abanoned, and the nodes of the graph
+    /// map reading rule will be abandoned, and the nodes of the graph
     /// will not be constructed, which usually cause that the arc set
-    /// could not be read due to lack of node name
-    /// resolving. Therefore, the \c skipArcs() should be used too, or
-    /// the useNodes() member function should be used to specify the
-    /// label of the nodes.
+    /// could not be read due to lack of node name resolving.
+    /// Therefore \c skipArcs() function should also be used, or
+    /// \c useNodes() should be used to specify the label of the nodes.
     DigraphReader& skipNodes() {
       LEMON_ASSERT(!_skip_nodes, "Skip nodes already set"); 
       _skip_nodes = true;
@@ -799,7 +798,7 @@
     /// \brief Skips the reading of arc section
     ///
     /// Omit the reading of the arc section. This implies that each arc
-    /// map reading rule will be abanoned, and the arcs of the graph
+    /// map reading rule will be abandoned, and the arcs of the graph
     /// will not be constructed.
     DigraphReader& skipArcs() {
       LEMON_ASSERT(!_skip_arcs, "Skip arcs already set"); 
@@ -1175,6 +1174,9 @@
     
   };
 
+  /// \brief Return a \ref DigraphReader class
+  /// 
+  /// This function just returns a \ref DigraphReader class.
   /// \relates DigraphReader
   template <typename Digraph>
   DigraphReader<Digraph> digraphReader(std::istream& is, Digraph& digraph) {
@@ -1182,6 +1184,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref DigraphReader class
+  /// 
+  /// This function just returns a \ref DigraphReader class.
   /// \relates DigraphReader
   template <typename Digraph>
   DigraphReader<Digraph> digraphReader(const std::string& fn, 
@@ -1190,6 +1195,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref DigraphReader class
+  /// 
+  /// This function just returns a \ref DigraphReader class.
   /// \relates DigraphReader
   template <typename Digraph>
   DigraphReader<Digraph> digraphReader(const char* fn, Digraph& digraph) {
@@ -1211,9 +1219,13 @@
 
   /// \ingroup lemon_io
   ///  
-  /// \brief LGF reader for undirected graphs
+  /// \brief \ref lgf-format "LGF" reader for undirected graphs
   ///
   /// This utility reads an \ref lgf-format "LGF" file.
+  ///
+  /// It can be used almost the same way as \c DigraphReader.
+  /// The only difference is that this class can handle edges and
+  /// edge maps as well as arcs and arc maps.
   template <typename _Graph>
   class GraphReader {
   public:
@@ -1262,7 +1274,7 @@
 
     /// \brief Constructor
     ///
-    /// Construct a undirected graph reader, which reads from the given
+    /// Construct an undirected graph reader, which reads from the given
     /// input stream.
     GraphReader(std::istream& is, Graph& graph) 
       : _is(&is), local_is(false), _graph(graph),
@@ -1271,7 +1283,7 @@
 
     /// \brief Constructor
     ///
-    /// Construct a undirected graph reader, which reads from the given
+    /// Construct an undirected graph reader, which reads from the given
     /// file.
     GraphReader(const std::string& fn, Graph& graph) 
       : _is(new std::ifstream(fn.c_str())), local_is(true), _graph(graph),
@@ -1280,7 +1292,7 @@
     
     /// \brief Constructor
     ///
-    /// Construct a undirected graph reader, which reads from the given
+    /// Construct an undirected graph reader, which reads from the given
     /// file.
     GraphReader(const char* fn, Graph& graph) 
       : _is(new std::ifstream(fn)), local_is(true), _graph(graph),
@@ -1497,7 +1509,7 @@
 
     /// \brief Set \c \@nodes section to be read
     ///
-    /// Set \c \@nodes section to be read
+    /// Set \c \@nodes section to be read.
     GraphReader& nodes(const std::string& caption) {
       _nodes_caption = caption;
       return *this;
@@ -1505,7 +1517,7 @@
 
     /// \brief Set \c \@edges section to be read
     ///
-    /// Set \c \@edges section to be read
+    /// Set \c \@edges section to be read.
     GraphReader& edges(const std::string& caption) {
       _edges_caption = caption;
       return *this;
@@ -1513,7 +1525,7 @@
 
     /// \brief Set \c \@attributes section to be read
     ///
-    /// Set \c \@attributes section to be read
+    /// Set \c \@attributes section to be read.
     GraphReader& attributes(const std::string& caption) {
       _attributes_caption = caption;
       return *this;
@@ -1544,7 +1556,7 @@
     ///
     /// Use previously constructed node set, and specify the node
     /// label map and a functor which converts the label map values to
-    /// std::string.
+    /// \c std::string.
     template <typename Map, typename Converter>
     GraphReader& useNodes(const Map& map, 
 			    const Converter& converter = Converter()) {
@@ -1577,7 +1589,7 @@
     ///
     /// Use previously constructed edge set, and specify the edge
     /// label map and a functor which converts the label map values to
-    /// std::string.
+    /// \c std::string.
     template <typename Map, typename Converter>
     GraphReader& useEdges(const Map& map, 
 			    const Converter& converter = Converter()) {
@@ -1590,25 +1602,25 @@
       return *this;
     }
 
-    /// \brief Skips the reading of node section
+    /// \brief Skip the reading of node section
     ///
     /// Omit the reading of the node section. This implies that each node
-    /// map reading rule will be abanoned, and the nodes of the graph
+    /// map reading rule will be abandoned, and the nodes of the graph
     /// will not be constructed, which usually cause that the edge set
     /// could not be read due to lack of node name
-    /// resolving. Therefore, the \c skipEdges() should be used too, or
-    /// the useNodes() member function should be used to specify the
-    /// label of the nodes.
+    /// could not be read due to lack of node name resolving.
+    /// Therefore \c skipEdges() function should also be used, or
+    /// \c useNodes() should be used to specify the label of the nodes.
     GraphReader& skipNodes() {
       LEMON_ASSERT(!_skip_nodes, "Skip nodes already set"); 
       _skip_nodes = true;
       return *this;
     }
 
-    /// \brief Skips the reading of edge section
+    /// \brief Skip the reading of edge section
     ///
     /// Omit the reading of the edge section. This implies that each edge
-    /// map reading rule will be abanoned, and the edges of the graph
+    /// map reading rule will be abandoned, and the edges of the graph
     /// will not be constructed.
     GraphReader& skipEdges() {
       LEMON_ASSERT(!_skip_edges, "Skip edges already set"); 
@@ -1982,6 +1994,9 @@
     
   };
 
+  /// \brief Return a \ref GraphReader class
+  /// 
+  /// This function just returns a \ref GraphReader class.
   /// \relates GraphReader
   template <typename Graph>
   GraphReader<Graph> graphReader(std::istream& is, Graph& graph) {
@@ -1989,6 +2004,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref GraphReader class
+  /// 
+  /// This function just returns a \ref GraphReader class.
   /// \relates GraphReader
   template <typename Graph>
   GraphReader<Graph> graphReader(const std::string& fn, 
@@ -1997,6 +2015,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref GraphReader class
+  /// 
+  /// This function just returns a \ref GraphReader class.
   /// \relates GraphReader
   template <typename Graph>
   GraphReader<Graph> graphReader(const char* fn, Graph& graph) {
@@ -2010,13 +2031,15 @@
   SectionReader sectionReader(const std::string& fn);
   SectionReader sectionReader(const char* fn);
   
+  /// \ingroup lemon_io
+  ///
   /// \brief Section reader class
   ///
-  /// In the \e LGF file extra sections can be placed, which contain
-  /// any data in arbitrary format. Such sections can be read with
-  /// this class. A reading rule can be added with two different
-  /// functions, with the \c sectionLines() function a functor can
-  /// process the section line-by-line. While with the \c
+  /// In the \ref lgf-format "LGF" file extra sections can be placed, 
+  /// which contain any data in arbitrary format. Such sections can be
+  /// read with this class. A reading rule can be added to the class 
+  /// with two different functions. With the \c sectionLines() function a
+  /// functor can process the section line-by-line, while with the \c
   /// sectionStream() member the section can be read from an input
   /// stream.
   class SectionReader {
@@ -2105,7 +2128,7 @@
     ///  23 6
     ///\endcode
     ///
-    /// The functor is implemented as an struct:
+    /// The functor is implemented as a struct:
     ///\code
     ///  struct NumberSection {
     ///    std::vector<int>& _data;
@@ -2123,7 +2146,7 @@
     ///\endcode
     template <typename Functor>
     SectionReader& sectionLines(const std::string& type, Functor functor) {
-      LEMON_ASSERT(!type.empty(), "Type is not empty.");
+      LEMON_ASSERT(!type.empty(), "Type is empty.");
       LEMON_ASSERT(_sections.find(type) == _sections.end(), 
 		   "Multiple reading of section.");
       _sections.insert(std::make_pair(type, 
@@ -2135,13 +2158,13 @@
     /// \brief Add a section processor with stream oriented reading
     ///
     /// The first parameter is the type of the section, the second is
-    /// a functor, which takes an \c std::istream& and an int&
+    /// a functor, which takes an \c std::istream& and an \c int&
     /// parameter, the latter regard to the line number of stream. The
     /// functor can read the input while the section go on, and the
     /// line number should be modified accordingly.
     template <typename Functor>
     SectionReader& sectionStream(const std::string& type, Functor functor) {
-      LEMON_ASSERT(!type.empty(), "Type is not empty.");
+      LEMON_ASSERT(!type.empty(), "Type is empty.");
       LEMON_ASSERT(_sections.find(type) == _sections.end(), 
 		   "Multiple reading of section.");
       _sections.insert(std::make_pair(type, 
@@ -2186,7 +2209,7 @@
 
     /// \brief Start the batch processing
     ///
-    /// This function starts the batch processing
+    /// This function starts the batch processing.
     void run() {
       
       LEMON_ASSERT(_is != 0, "This reader assigned to an other reader");
@@ -2239,18 +2262,27 @@
         
   };
 
+  /// \brief Return a \ref SectionReader class
+  /// 
+  /// This function just returns a \ref SectionReader class.
   /// \relates SectionReader
   inline SectionReader sectionReader(std::istream& is) {
     SectionReader tmp(is);
     return tmp;
   }
 
+  /// \brief Return a \ref SectionReader class
+  /// 
+  /// This function just returns a \ref SectionReader class.
   /// \relates SectionReader
   inline SectionReader sectionReader(const std::string& fn) {
     SectionReader tmp(fn);
     return tmp;
   }
 
+  /// \brief Return a \ref SectionReader class
+  /// 
+  /// This function just returns a \ref SectionReader class.
   /// \relates SectionReader
   inline SectionReader sectionReader(const char* fn) {
     SectionReader tmp(fn);
@@ -2269,19 +2301,20 @@
   /// reads the graph and stores the appropriate information for
   /// reading the graph.
   ///
-  ///\code LgfContents contents("graph.lgf"); 
+  ///\code 
+  /// LgfContents contents("graph.lgf"); 
   /// contents.run();
   ///
-  /// // does it contain any node section and arc section
+  /// // Does it contain any node section and arc section?
   /// if (contents.nodeSectionNum() == 0 || contents.arcSectionNum()) {
-  ///   std::cerr << "Failure, cannot find graph" << std::endl;
+  ///   std::cerr << "Failure, cannot find graph." << std::endl;
   ///   return -1;
   /// }
-  /// std::cout << "The name of the default node section : " 
+  /// std::cout << "The name of the default node section: " 
   ///           << contents.nodeSection(0) << std::endl;
-  /// std::cout << "The number of the arc maps : " 
+  /// std::cout << "The number of the arc maps: " 
   ///           << contents.arcMaps(0).size() << std::endl;
-  /// std::cout << "The name of second arc map : " 
+  /// std::cout << "The name of second arc map: " 
   ///           << contents.arcMaps(0)[1] << std::endl;
   ///\endcode
   class LgfContents {    
@@ -2352,9 +2385,9 @@
       return _node_sections.size();
     }
 
-    /// \brief Returns the section name at the given position. 
+    /// \brief Returns the node section name at the given position. 
     ///
-    /// Returns the section name at the given position. 
+    /// Returns the node section name at the given position. 
     const std::string& nodeSection(int i) const {
       return _node_sections[i];
     }
@@ -2379,9 +2412,9 @@
       return _edge_sections.size();
     }
 
-    /// \brief Returns the section name at the given position. 
+    /// \brief Returns the arc/edge section name at the given position. 
     ///
-    /// Returns the section name at the given position. 
+    /// Returns the arc/edge section name at the given position. 
     /// \note It is synonym of \c edgeSection().
     const std::string& arcSection(int i) const {
       return _edge_sections[i];
@@ -2436,9 +2469,9 @@
       return _attribute_sections.size();
     }
 
-    /// \brief Returns the section name at the given position. 
+    /// \brief Returns the attribute section name at the given position. 
     ///
-    /// Returns the section name at the given position. 
+    /// Returns the attribute section name at the given position. 
     const std::string& attributeSectionNames(int i) const {
       return _attribute_sections[i];
     }
@@ -2529,9 +2562,9 @@
     /// \name Execution of the contents reader    
     /// @{
 
-    /// \brief Start the reading
+    /// \brief Starts the reading
     ///
-    /// This function starts the reading
+    /// This function starts the reading.
     void run() {
 
       readLine();
diff -r 1e6af6f0843c -r 7bf5f97d574f lemon/lgf_writer.h
--- a/lemon/lgf_writer.h	Fri Jul 04 16:12:31 2008 +0200
+++ b/lemon/lgf_writer.h	Sat Jul 05 00:14:27 2008 +0200
@@ -18,7 +18,7 @@
 
 ///\ingroup lemon_io
 ///\file
-///\brief Lemon Graph Format writer.
+///\brief \ref lgf-format "Lemon Graph Format" writer.
 
 
 #ifndef LEMON_LGF_WRITER_H
@@ -322,7 +322,7 @@
   
   /// \ingroup lemon_io
   ///  
-  /// \brief LGF writer for directed graphs
+  /// \brief \ref lgf-format "LGF" writer for directed graphs
   ///
   /// This utility writes an \ref lgf-format "LGF" file.
   ///
@@ -332,22 +332,22 @@
   /// member function. A map writing rule can be added to the writer
   /// with the \c nodeMap() or \c arcMap() members. An optional
   /// converter parameter can also be added as a standard functor
-  /// converting from the value type of the map to std::string. If it
-  /// is set, it will determine how the map's value type is written to
+  /// converting from the value type of the map to \c std::string. If it
+  /// is set, it will determine how the value type of the map is written to
   /// the output stream. If the functor is not set, then a default
   /// conversion will be used. The \c attribute(), \c node() and \c
   /// arc() functions are used to add attribute writing rules.
   ///
   ///\code
-  ///     DigraphWriter<Digraph>(std::cout, digraph).
-  ///       nodeMap("coordinates", coord_map).
-  ///       nodeMap("size", size).
-  ///       nodeMap("title", title).
-  ///       arcMap("capacity", cap_map).
-  ///       node("source", src).
-  ///       node("target", trg).
-  ///       attribute("caption", caption).
-  ///       run();
+  /// DigraphWriter<Digraph>(std::cout, digraph).
+  ///   nodeMap("coordinates", coord_map).
+  ///   nodeMap("size", size).
+  ///   nodeMap("title", title).
+  ///   arcMap("capacity", cap_map).
+  ///   node("source", src).
+  ///   node("target", trg).
+  ///   attribute("caption", caption).
+  ///   run();
   ///\endcode
   ///
   ///
@@ -486,9 +486,9 @@
     /// \name Writing rules
     /// @{
     
-    /// \brief Node map reading rule
+    /// \brief Node map writing rule
     ///
-    /// Add a node map reading rule to the writer.
+    /// Add a node map writing rule to the writer.
     template <typename Map>
     DigraphWriter& nodeMap(const std::string& caption, const Map& map) {
       checkConcept<concepts::ReadMap<Node, typename Map::Value>, Map>();
@@ -586,28 +586,28 @@
       return *this;
     }
 
-    /// \name Select section by name
+    /// \name Section captions
     /// @{
 
-    /// \brief Set \c \@nodes section to be read
+    /// \brief Add an additional caption to the \c \@nodes section
     ///
-    /// Set \c \@nodes section to be read
+    /// Add an additional caption to the \c \@nodes section.
     DigraphWriter& nodes(const std::string& caption) {
       _nodes_caption = caption;
       return *this;
     }
 
-    /// \brief Set \c \@arcs section to be read
+    /// \brief Add an additional caption to the \c \@arcs section
     ///
-    /// Set \c \@arcs section to be read
+    /// Add an additional caption to the \c \@arcs section.
     DigraphWriter& arcs(const std::string& caption) {
       _arcs_caption = caption;
       return *this;
     }
 
-    /// \brief Set \c \@attributes section to be read
+    /// \brief Add an additional caption to the \c \@attributes section
     ///
-    /// Set \c \@attributes section to be read
+    /// Add an additional caption to the \c \@attributes section.
     DigraphWriter& attributes(const std::string& caption) {
       _attributes_caption = caption;
       return *this;
@@ -618,7 +618,7 @@
 
     /// \brief Skip writing the node set
     ///
-    /// The \c \@nodes section will be not written to the stream.
+    /// The \c \@nodes section will not be written to the stream.
     DigraphWriter& skipNodes() {
       LEMON_ASSERT(!_skip_nodes, "Multiple usage of skipNodes() member");
       _skip_nodes = true;
@@ -627,7 +627,7 @@
 
     /// \brief Skip writing arc set
     ///
-    /// The \c \@arcs section will be not written to the stream.
+    /// The \c \@arcs section will not be written to the stream.
     DigraphWriter& skipArcs() {
       LEMON_ASSERT(!_skip_arcs, "Multiple usage of skipArcs() member");
       _skip_arcs = true;
@@ -835,7 +835,7 @@
 
     /// \brief Start the batch processing
     ///
-    /// This function starts the batch processing
+    /// This function starts the batch processing.
     void run() {
       if (!_skip_nodes) {
 	writeNodes();
@@ -850,9 +850,9 @@
       writeAttributes();
     }
 
-    /// \brief Gives back the stream of the writer
+    /// \brief Give back the stream of the writer
     ///
-    /// Gives back the stream of the writer
+    /// Give back the stream of the writer.
     std::ostream& ostream() {
       return *_os;
     }
@@ -860,6 +860,9 @@
     /// @}
   };
 
+  /// \brief Return a \ref DigraphWriter class
+  /// 
+  /// This function just returns a \ref DigraphWriter class.
   /// \relates DigraphWriter
   template <typename Digraph>
   DigraphWriter<Digraph> digraphWriter(std::ostream& os, 
@@ -868,6 +871,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref DigraphWriter class
+  /// 
+  /// This function just returns a \ref DigraphWriter class.
   /// \relates DigraphWriter
   template <typename Digraph>
   DigraphWriter<Digraph> digraphWriter(const std::string& fn, 
@@ -876,6 +882,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref DigraphWriter class
+  /// 
+  /// This function just returns a \ref DigraphWriter class.
   /// \relates DigraphWriter
   template <typename Digraph>
   DigraphWriter<Digraph> digraphWriter(const char* fn, 
@@ -898,9 +907,13 @@
 
   /// \ingroup lemon_io
   ///  
-  /// \brief LGF writer for directed graphs
+  /// \brief \ref lgf-format "LGF" writer for directed graphs
   ///
   /// This utility writes an \ref lgf-format "LGF" file.
+  ///
+  /// It can be used almost the same way as \c DigraphWriter.
+  /// The only difference is that this class can handle edges and
+  /// edge maps as well as arcs and arc maps.
   template <typename _Graph>
   class GraphWriter {
   public:
@@ -1023,9 +1036,9 @@
     /// \name Writing rules
     /// @{
     
-    /// \brief Node map reading rule
+    /// \brief Node map writing rule
     ///
-    /// Add a node map reading rule to the writer.
+    /// Add a node map writing rule to the writer.
     template <typename Map>
     GraphWriter& nodeMap(const std::string& caption, const Map& map) {
       checkConcept<concepts::ReadMap<Node, typename Map::Value>, Map>();
@@ -1169,28 +1182,28 @@
       return *this;
     }
 
-    /// \name Select section by name
+    /// \name Section captions
     /// @{
 
-    /// \brief Set \c \@nodes section to be read
+    /// \brief Add an additional caption to the \c \@nodes section
     ///
-    /// Set \c \@nodes section to be read
+    /// Add an additional caption to the \c \@nodes section.
     GraphWriter& nodes(const std::string& caption) {
       _nodes_caption = caption;
       return *this;
     }
 
-    /// \brief Set \c \@edges section to be read
+    /// \brief Add an additional caption to the \c \@arcs section
     ///
-    /// Set \c \@edges section to be read
+    /// Add an additional caption to the \c \@arcs section.
     GraphWriter& edges(const std::string& caption) {
       _edges_caption = caption;
       return *this;
     }
 
-    /// \brief Set \c \@attributes section to be read
+    /// \brief Add an additional caption to the \c \@attributes section
     ///
-    /// Set \c \@attributes section to be read
+    /// Add an additional caption to the \c \@attributes section.
     GraphWriter& attributes(const std::string& caption) {
       _attributes_caption = caption;
       return *this;
@@ -1201,7 +1214,7 @@
 
     /// \brief Skip writing the node set
     ///
-    /// The \c \@nodes section will be not written to the stream.
+    /// The \c \@nodes section will not be written to the stream.
     GraphWriter& skipNodes() {
       LEMON_ASSERT(!_skip_nodes, "Multiple usage of skipNodes() member");
       _skip_nodes = true;
@@ -1210,7 +1223,7 @@
 
     /// \brief Skip writing edge set
     ///
-    /// The \c \@edges section will be not written to the stream.
+    /// The \c \@edges section will not be written to the stream.
     GraphWriter& skipEdges() {
       LEMON_ASSERT(!_skip_edges, "Multiple usage of skipEdges() member");
       _skip_edges = true;
@@ -1418,7 +1431,7 @@
 
     /// \brief Start the batch processing
     ///
-    /// This function starts the batch processing
+    /// This function starts the batch processing.
     void run() {
       if (!_skip_nodes) {
 	writeNodes();
@@ -1433,9 +1446,9 @@
       writeAttributes();
     }
 
-    /// \brief Gives back the stream of the writer
+    /// \brief Give back the stream of the writer
     ///
-    /// Gives back the stream of the writer
+    /// Give back the stream of the writer
     std::ostream& ostream() {
       return *_os;
     }
@@ -1443,6 +1456,9 @@
     /// @}
   };
 
+  /// \brief Return a \ref GraphWriter class
+  /// 
+  /// This function just returns a \ref GraphWriter class.
   /// \relates GraphWriter
   template <typename Graph>
   GraphWriter<Graph> graphWriter(std::ostream& os, const Graph& graph) {
@@ -1450,6 +1466,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref GraphWriter class
+  /// 
+  /// This function just returns a \ref GraphWriter class.
   /// \relates GraphWriter
   template <typename Graph>
   GraphWriter<Graph> graphWriter(const std::string& fn, const Graph& graph) {
@@ -1457,6 +1476,9 @@
     return tmp;
   }
 
+  /// \brief Return a \ref GraphWriter class
+  /// 
+  /// This function just returns a \ref GraphWriter class.
   /// \relates GraphWriter
   template <typename Graph>
   GraphWriter<Graph> graphWriter(const char* fn, const Graph& graph) {