lemon-1.2: comparison lemon/lgf

equal deleted inserted replaced

-:61133d65d026
+:a44ec635a2db
 *
 */
 ///\ingroup lemon_io
 ///\file
-///\brief Lemon Graph Format reader.
+///\brief \ref lgf-format "Lemon Graph Format" reader.
 #ifndef LEMON_LGF_READER_H
 #define LEMON_LGF_READER_H
 template <typename Digraph>
 DigraphReader<Digraph> digraphReader(const char *fn, Digraph& digraph);
 /// \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.
 ///
 /// The reading method does a batch processing. The user creates a
 /// reader object, then various reading rules can be added to the
 /// reader, and eventually the reading is executed with the \c run()
 /// 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).
+/// DigraphReader<Digraph>(std::cin, digraph).
-///       nodeMap("coordinates", coord_map).
+///   nodeMap("coordinates", coord_map).
-///       arcMap("capacity", cap_map).
+///   arcMap("capacity", cap_map).
-///       node("source", src).
+///   node("source", src).
-///       node("target", trg).
+///   node("target", trg).
-///       attribute("caption", caption).
+///   attribute("caption", caption).
-///       run();
+///   run();
 ///\endcode
 ///
 /// By default the reader uses the first section in the file of the
 /// proper type. If a section has an optional name, then it can be
 /// selected for reading by giving an optional name parameter to the
 ///
 /// The \c useNodes() and \c useArcs() functions are used to tell the reader
 /// 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
+/// application of these functions is multipass reading, which is
-/// important if two \e \@arcs sections must be read from the
+/// important if two \c \@arcs sections must be read from the
-/// file. In this example the first phase would read the node set and one
+/// 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>
 class DigraphReader {
 public:
 /// \brief Use previously constructed node set
 ///
 /// 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()) {
 checkConcept<concepts::ReadMap<Node, typename Map::Value>, Map>();
 LEMON_ASSERT(!_use_nodes, "Multiple usage of useNodes() member");
 /// \brief Use previously constructed arc set
 ///
 /// 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()) {
 checkConcept<concepts::ReadMap<Arc, typename Map::Value>, Map>();
 LEMON_ASSERT(!_use_arcs, "Multiple usage of useArcs() member");
 }
 /// \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
+/// could not be read due to lack of node name resolving.
-/// resolving. Therefore, the \c skipArcs() should be used too, or
+/// Therefore \c skipArcs() function should also be used, or
-/// the useNodes() member function should be used to specify the
+/// \c useNodes() should be used to specify the label of the nodes.
-/// label of the nodes.
 DigraphReader& skipNodes() {
 LEMON_ASSERT(!_skip_nodes, "Skip nodes already set");
 _skip_nodes = true;
 return *this;
 }
 /// \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");
 _skip_arcs = true;
 return *this;
 /// @}
 };
+/// \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) {
 DigraphReader<Digraph> tmp(is, digraph);
 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,
 				       Digraph& digraph) {
 DigraphReader<Digraph> tmp(fn, digraph);
 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) {
 DigraphReader<Digraph> tmp(fn, digraph);
 return tmp;
 template <typename Graph>
 GraphReader<Graph> graphReader(const char *fn, Graph& graph);
 /// \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:
 typedef _Graph Graph;
 public:
 /// \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),
 	_use_nodes(false), _use_edges(false),
 	_skip_nodes(false), _skip_edges(false) {}
 /// \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),
 	_use_nodes(false), _use_edges(false),
 	_skip_nodes(false), _skip_edges(false) {}
 /// \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),
 	_use_nodes(false), _use_edges(false),
 	_skip_nodes(false), _skip_edges(false) {}
 /// \name Select section by name
 /// @{
 /// \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;
 }
 /// \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;
 }
 /// \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;
 }
 /// \brief Use previously constructed node set
 ///
 /// 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()) {
 checkConcept<concepts::ReadMap<Node, typename Map::Value>, Map>();
 LEMON_ASSERT(!_use_nodes, "Multiple usage of useNodes() member");
 /// \brief Use previously constructed edge set
 ///
 /// 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()) {
 checkConcept<concepts::ReadMap<Edge, typename Map::Value>, Map>();
 LEMON_ASSERT(!_use_edges, "Multiple usage of useEdges() member");
 	_edge_index.insert(std::make_pair(converter(map[a]), a));
 }
 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
+/// could not be read due to lack of node name resolving.
-/// the useNodes() member function should be used to specify the
+/// Therefore \c skipEdges() function should also be used, or
-/// label of the nodes.
+/// \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");
 _skip_edges = true;
 return *this;
 /// @}
 };
+/// \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) {
 GraphReader<Graph> tmp(is, graph);
 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,
 				       Graph& graph) {
 GraphReader<Graph> tmp(fn, graph);
 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) {
 GraphReader<Graph> tmp(fn, graph);
 return tmp;
 SectionReader sectionReader(std::istream& is);
 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
+/// In the \ref lgf-format "LGF" file extra sections can be placed,
-/// any data in arbitrary format. Such sections can be read with
+/// which contain any data in arbitrary format. Such sections can be
-/// this class. A reading rule can be added with two different
+/// read with this class. A reading rule can be added to the class
-/// functions, with the \c sectionLines() function a functor can
+/// with two different functions. With the \c sectionLines() function a
-/// process the section line-by-line. While with the \c
+/// 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 {
 private:
 ///  12 45 23
 ///  4
 ///  23 6
 ///\endcode
 ///
-/// The functor is implemented as an struct:
+/// The functor is implemented as a struct:
 ///\code
 ///  struct NumberSection {
 ///    std::vector<int>& _data;
 ///    NumberSection(std::vector<int>& data) : _data(data) {}
 ///    void operator()(const std::string& line) {
 ///
 ///  reader.sectionLines("numbers", NumberSection(vec));
 ///\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,
 new _reader_bits::LineSection<Functor>(functor)));
 return *this;
 /// \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,
 	 new _reader_bits::StreamSection<Functor>(functor)));
 return *this;
 /// \name Execution of the reader
 /// @{
 /// \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");
 std::set<std::string> extra_sections;
 /// @}
 };
+/// \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);
 return tmp;
 }
 /// should be read from a file, but in general tools (like glemon)
 /// the contents of an LGF file should be guessed somehow. This class
 /// 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 {
 private:
 /// Gives back the number of node sections in the file.
 int nodeSectionNum() const {
 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];
 }
 /// \brief Gives back the node maps for the given section.
 /// \note It is synonym of \c edgeSectionNum().
 int arcSectionNum() const {
 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];
 }
 /// Gives back the number of attribute sections in the file.
 int attributeSectionNum() const {
 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];
 }
 /// \brief Gives back the attributes for the given section.
 public:
 /// \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();
 skipSection();

changeset 195	aa45ff44fcf3
parent 190	1e6af6f0843c
child 197	5893bacaa720