lemon-0.x: comparison lemon/graph

equal deleted inserted replaced

-:8091c8f3eaef
+:0c1fbae3474f
 /// \addtogroup io_group
 /// @{
 /// \brief The graph writer class.
 ///
-/// The \c GraphWriter class provides the graph output. To write a graph
+/// The \c GraphWriter class provides the graph output.
-/// you should first give writing commands for the writer. You can declare
+/// Before you read this documentation it might be useful to read the general
-/// write command as \c NodeMap or \c EdgeMap writing and labeled Node and
+/// description of  \ref graph-io-page "Graph Input-Output".
+/// To write a graph
+/// you should first give writing commands to the writer. You can declare
+/// write commands as \c NodeMap or \c EdgeMap writing and labeled Node and
 /// Edge writing.
 ///
 /// \code
 /// GraphWriter<ListGraph> writer(std::cout, graph);
 /// \endcode
 ///
 /// The \c writeNodeMap() function declares a \c NodeMap writing
 /// command in the \c GraphWriter. You should give as parameter
 /// the name of the map and the map object. The NodeMap writing
 /// command with name "id" should write a unique map because it
-/// is regarded as ID map.
+/// is regarded as ID map (such a map is essential if the graph has edges).
 ///
 /// \code
 /// IdMap<ListGraph, Node> nodeIdMap;
 /// writer.writeNodeMap("id", nodeIdMap);
 ///
 /// writer.writeEdgeMap("weight", weightMap);
 /// writer.writeEdgeMap("label", labelMap);
 /// \endcode
 ///
 /// With \c writeNode() and \c writeEdge() functions you can
-/// point out Nodes and Edges in the graph. By example, you can
+/// point out Nodes and Edges in the graph. For example, you can
-/// write out the source and target of the graph.
+/// write out the source and target of a maximum flow instance.
 ///
 /// \code
 /// writer.writeNode("source", sourceNode);
 /// writer.writeNode("target", targetNode);
 ///
 /// writer.writeEdge("observed", edge);
 /// \endcode
 ///
 /// After you give all write commands you must call the \c run() member
-/// function, which execute all the writer commands.
+/// function, which executes all the writing commands.
 ///
 /// \code
 /// writer.run();
 /// \endcode
 ///
 typedef _WriterTraits WriterTraits;
 /// \brief Construct a new GraphWriter.
 ///
-/// Construct a new GraphWriter. It writes the given graph
+/// This function constructs a new GraphWriter to write the given graph
 /// to the given stream.
 GraphWriter(std::ostream& _os, const Graph& _graph)
 : writer(new LemonWriter(_os)), own_writer(true),
 	nodeset_writer(*writer, _graph, std::string()),
 	edgeset_writer(*writer, _graph, nodeset_writer, std::string()),
 	edge_writer(*writer, edgeset_writer, std::string()),
 	attribute_writer(*writer, std::string()) {}
 /// \brief Construct a new GraphWriter.
 ///
-/// Construct a new GraphWriter. It writes into the given graph
+/// This function constructs a new GraphWriter to write the given graph
 /// to the given file.
 GraphWriter(const std::string& _filename, const Graph& _graph)
 : writer(new LemonWriter(_filename)), own_writer(true),
 	nodeset_writer(*writer, _graph, std::string()),
 	edgeset_writer(*writer, _graph, nodeset_writer, std::string()),
 	edge_writer(*writer, edgeset_writer, std::string()),
 	attribute_writer(*writer, std::string()) {}
 /// \brief Construct a new GraphWriter.
 ///
-/// Construct a new GraphWriter. It writes into the given graph
+/// This function constructs a new GraphWriter to write the given graph
-/// to given LemonReader.
+/// to the given LemonReader.
 GraphWriter(LemonWriter& _writer, const Graph& _graph)
 : writer(_writer), own_writer(false),
 	nodeset_writer(*writer, _graph, std::string()),
 	edgeset_writer(*writer, _graph, nodeset_writer, std::string()),
 	node_writer(*writer, nodeset_writer, std::string()),
 	edge_writer(*writer, edgeset_writer, std::string()),
 	attribute_writer(*writer, std::string()) {}
 /// \brief Destruct the graph writer.
 ///
-/// Destruct the graph writer.
+/// This function destructs the graph writer.
 ~GraphWriter() {
 if (own_writer)
 	delete writer;
 }
-/// \brief Add a new node map writer command for the writer.
+/// \brief Issue a new node map writing command for the writer.
 ///
-/// Add a new node map writer command for the writer.
+/// This function issues a new <i> node map writing command</i> to the writer.
 template <typename Map>
 GraphWriter& writeNodeMap(std::string name, const Map& map) {
 nodeset_writer.writeNodeMap(name, map);
 return *this;
 }
-/// \brief Add a new node map writer command for the writer.
+/// \brief Issue a new node map writing command for the writer.
 ///
-/// Add a new node map writer command for the writer.
+/// This function issues a new <i> node map writing command</i> to the writer.
 template <typename Writer, typename Map>
 GraphWriter& writeNodeMap(std::string name, const Map& map,
 			      const Writer& writer = Writer()) {
 nodeset_writer.writeNodeMap(name, map, writer);
 return *this;
 }
-/// \brief Add a new edge map writer command for the writer.
+/// \brief Issue a new edge map writing command for the writer.
 ///
-/// Add a new edge map writer command for the writer.
+/// This function issues a new <i> edge map writing command</i> to the writer.
 template <typename Map>
 GraphWriter& writeEdgeMap(std::string name, const Map& map) {
 edgeset_writer.writeEdgeMap(name, map);
 return *this;
 }
-/// \brief Add a new edge map writer command for the writer.
+/// \brief Issue a new edge map writing command for the writer.
 ///
-/// Add a new edge map writer command for the writer.
+/// This function issues a new <i> edge map writing command</i> to the writer.
 template <typename Writer, typename Map>
 GraphWriter& writeEdgeMap(std::string name, const Map& map,
 			      const Writer& writer = Writer()) {
 edgeset_writer.writeEdgeMap(name, map, writer);
 return *this;
 }
-/// \brief Add a new labeled node writer for the writer.
+/// \brief Issue a new labeled node writing command to the writer.
 ///
-/// Add a new labeled node writer for the writer.
+/// This function issues a new <i> labeled node writing command</i>
+/// to the writer.
 GraphWriter& writeNode(std::string name, const Node& node) {
 node_writer.writeNode(name, node);
 return *this;
 }
-/// \brief Add a new labeled edge writer for the writer.
+/// \brief Issue a new labeled edge writing command to the writer.
 ///
-/// Add a new labeled edge writer for the writer.
+/// This function issues a new <i> labeled edge writing command</i>
+/// to the writer.
 GraphWriter& writeEdge(std::string name, const Edge& edge) {
 edge_writer.writeEdge(name, edge);
 }
-/// \brief Add a new attribute writer command.
+/// \brief Issue a new attribute writing command.
 ///
-///  Add a new attribute writer command.
+/// This function issues a new <i> attribute writing command</i>
+/// to the writer.
 template <typename Value>
 GraphWriter& writeAttribute(std::string name, const Value& value) {
 attribute_writer.writeAttribute(name, value);
 return *this;
 }
-/// \brief Add a new attribute writer command.
+/// \brief Issue a new attribute writing command.
 ///
-///  Add a new attribute writer command.
+/// This function issues a new <i> attribute writing command</i>
+/// to the writer.
 template <typename Writer, typename Value>
 GraphWriter& writeAttribute(std::string name, const Value& value,
 			       const Writer& writer) {
 attribute_writer.writeAttribute<Writer>(name, value, writer);
 return *this;
 }
 /// \brief Conversion operator to LemonWriter.
 ///
-/// Conversion operator to LemonWriter. It make possible
+/// Conversion operator to LemonWriter. It makes possible
 /// to access the encapsulated \e LemonWriter, this way
 /// you can attach to this writer new instances of
 /// \e LemonWriter::SectionWriter.
 operator LemonWriter&() {
 return *writer;
 }
-/// \brief Executes the writer commands.
+/// \brief Executes the writing commands.
 ///
-/// Executes the writer commands.
+/// Executes the writing commands.
 void run() {
 writer->run();
 }
 /// \brief Write the id of the given node.
 ///
 /// It writes the id of the given node. If there was written an "id"
-/// named node map then it will write the map value belongs to the node.
+/// named node map then it will write the map value belonging to the node.
 void writeId(std::ostream& os, const Node& item) const {
 nodeset_writer.writeId(os, item);
 }
 /// \brief Write the id of the given edge.
 ///
 /// It writes the id of the given edge. If there was written an "id"
-/// named edge map then it will write the map value belongs to the edge.
+/// named edge map then it will write the map value belonging to the edge.
 void writeId(std::ostream& os, const Edge& item) const {
 edgeset_writer.writeId(os, item);
 }
 private:
 }
 /// \brief The undirected graph writer class.
 ///
 /// The \c UndirGraphWriter class provides the undir graph output. To write
-/// a graph you should first give writing commands for the writer. You can
+/// a graph you should first give writing commands to the writer. You can
 /// declare write command as \c NodeMap, \c EdgeMap or \c UndirEdgeMap
 /// writing and labeled Node, Edge or UndirEdge writing.
 ///
 /// \code
 /// UndirGraphWriter<UndirListGraph> writer(std::cout, graph);
 /// writer.writeEdgeMap("capacity", capacityMap);
 /// \endcode
 ///
 ///
 /// With \c writeNode() and \c writeUndirEdge() functions you can
-/// point out nodes and undirected edges in the graph. By example, you can
+/// designate nodes and undirected edges in the graph. For example, you can
 /// write out the source and target of the graph.
 ///
 /// \code
 /// writer.writeNode("source", sourceNode);
 /// writer.writeNode("target", targetNode);
 ///
 /// writer.writeUndirEdge("observed", undirEdge);
 /// \endcode
 ///
 /// After you give all write commands you must call the \c run() member
-/// function, which execute all the writer commands.
+/// function, which executes all the writing commands.
 ///
 /// \code
 /// writer.run();
 /// \endcode
 ///
 	undir_edge_writer(*writer, undir_edgeset_writer, std::string()),
 	attribute_writer(*writer, std::string()) {}
 /// \brief Construct a new UndirGraphWriter.
 ///
-/// Construct a new UndirGraphWriter. It writes into the given graph
+/// Construct a new UndirGraphWriter. It writes the given graph
 /// to the given file.
 UndirGraphWriter(const std::string& _filename, const Graph& _graph)
 : writer(new LemonWriter(_filename)), own_writer(true),
 	nodeset_writer(*writer, _graph, std::string()),
 	undir_edgeset_writer(*writer, _graph, nodeset_writer, std::string()),
 	undir_edge_writer(*writer, undir_edgeset_writer, std::string()),
 	attribute_writer(*writer, std::string()) {}
 /// \brief Construct a new UndirGraphWriter.
 ///
-/// Construct a new UndirGraphWriter. It writes into the given graph
+/// Construct a new UndirGraphWriter. It writes the given graph
 /// to given LemonReader.
 UndirGraphWriter(LemonWriter& _writer, const Graph& _graph)
 : writer(_writer), own_writer(false),
 	nodeset_writer(*writer, _graph, std::string()),
 	undir_edgeset_writer(*writer, _graph, nodeset_writer, std::string()),
 ~UndirGraphWriter() {
 if (own_writer)
 	delete writer;
 }
-/// \brief Add a new node map writer command for the writer.
+/// \brief Issue a new node map writing command to the writer.
 ///
-/// Add a new node map writer command for the writer.
+/// This function issues a new <i> node map writing command</i> to the writer.
 template <typename Map>
 UndirGraphWriter& writeNodeMap(std::string name, const Map& map) {
 nodeset_writer.writeNodeMap(name, map);
 return *this;
 }
-/// \brief Add a new node map writer command for the writer.
+/// \brief Issue a new node map writing command to the writer.
 ///
-/// Add a new node map writer command for the writer.
+/// This function issues a new <i> node map writing command</i> to the writer.
 template <typename Writer, typename Map>
 UndirGraphWriter& writeNodeMap(std::string name, const Map& map,
 			      const Writer& writer = Writer()) {
 nodeset_writer.writeNodeMap(name, map, writer);
 return *this;
 }
-/// \brief Add a new edge map writer command for the writer.
+/// \brief Issue a new edge map writing command to the writer.
 ///
-/// Add a new edge map writer command for the writer.
+/// This function issues a new <i> edge map writing command</i> to the writer.
 template <typename Map>
 UndirGraphWriter& writeEdgeMap(std::string name, const Map& map) {
 undir_edgeset_writer.writeEdgeMap(name, map);
 return *this;
 }
-/// \brief Add a new edge map writer command for the writer.
+/// \brief Issue a new edge map writing command to the writer.
 ///
-/// Add a new edge map writer command for the writer.
+/// This function issues a new <i> edge map writing command</i> to the writer.
 template <typename Writer, typename Map>
 UndirGraphWriter& writeEdgeMap(std::string name, const Map& map,
 				   const Writer& writer = Writer()) {
 undir_edgeset_writer.writeEdgeMap(name, map, writer);
 return *this;
 }
-/// \brief Add a new undirected edge map writer command for the writer.
+/// \brief Issue a new undirected edge map writing command to the writer.
 ///
-/// Add a new undirected edge map writer command for the writer.
+/// This function issues a new <i> undirected edge map writing
+/// command</i> to the writer.
 template <typename Map>
 UndirGraphWriter& writeUndirEdgeMap(std::string name, const Map& map) {
 undir_edgeset_writer.writeUndirEdgeMap(name, map);
 return *this;
 }
-/// \brief Add a new undirected edge map writer command for the writer.
+/// \brief Issue a new undirected edge map writing command to the writer.
 ///
-/// Add a new edge undirected map writer command for the writer.
+/// This function issues a new <i> undirected edge map writing
+/// command</i> to the writer.
 template <typename Writer, typename Map>
 UndirGraphWriter& writeUndirEdgeMap(std::string name, const Map& map,
 					const Writer& writer = Writer()) {
 undir_edgeset_writer.writeUndirEdgeMap(name, map, writer);
 return *this;
 }
-/// \brief Add a new labeled node writer for the writer.
+/// \brief Issue a new labeled node writer to the writer.
 ///
-/// Add a new labeled node writer for the writer.
+/// This function issues a new <i> labeled node writing
+/// command</i> to the writer.
 UndirGraphWriter& writeNode(std::string name, const Node& node) {
 node_writer.writeNode(name, node);
 return *this;
 }
-/// \brief Add a new labeled edge writer for the writer.
+/// \brief Issue a new labeled edge writer to the writer.
 ///
-/// Add a new labeled edge writer for the writer.
+/// This function issues a new <i> labeled edge writing
+/// command</i> to the writer.
 UndirGraphWriter& writeEdge(std::string name, const Edge& edge) {
 undir_edge_writer.writeEdge(name, edge);
 }
-/// \brief Add a new labeled undirected edge writer for the writer.
+/// \brief Issue a new labeled undirected edge writing command to
-///
+/// the writer.
-/// Add a new labeled undirected edge writer for the writer.
+///
+/// Issue a new <i>labeled undirected edge writing command</i> to
+/// the writer.
 UndirGraphWriter& writeUndirEdge(std::string name, const UndirEdge& edge) {
 undir_edge_writer.writeUndirEdge(name, edge);
 }
-/// \brief Add a new attribute writer command.
+/// \brief Issue a new attribute writing command.
 ///
-///  Add a new attribute writer command.
+/// This function issues a new <i> attribute writing
+/// command</i> to the writer.
 template <typename Value>
 UndirGraphWriter& writeAttribute(std::string name, const Value& value) {
 attribute_writer.writeAttribute(name, value);
 return *this;
 }
-/// \brief Add a new attribute writer command.
+/// \brief Issue a new attribute writing command.
 ///
-///  Add a new attribute writer command.
+/// This function issues a new <i> attribute writing
+/// command</i> to the writer.
 template <typename Writer, typename Value>
 UndirGraphWriter& writeAttribute(std::string name, const Value& value,
 			       const Writer& writer) {
 attribute_writer.writeAttribute<Writer>(name, value, writer);
 return *this;
 }
 /// \brief Conversion operator to LemonWriter.
 ///
-/// Conversion operator to LemonWriter. It make possible
+/// Conversion operator to LemonWriter. It makes possible
 /// to access the encapsulated \e LemonWriter, this way
 /// you can attach to this writer new instances of
 /// \e LemonWriter::SectionWriter.
 operator LemonWriter&() {
 return *writer;
 }
-/// \brief Executes the writer commands.
+/// \brief Executes the writing commands.
 ///
-/// Executes the writer commands.
+/// Executes the writing commands.
 void run() {
 writer->run();
 }
 /// \brief Write the id of the given node.
 ///
 /// It writes the id of the given node. If there was written an "id"
-/// named node map then it will write the map value belongs to the node.
+/// named node map then it will write the map value belonging to the node.
 void writeId(std::ostream& os, const Node& item) const {
 nodeset_writer.writeId(os, item);
 }
 /// \brief Write the id of the given edge.
 ///
 /// It writes the id of the given edge. If there was written an "id"
-/// named edge map then it will write the map value belongs to the edge.
+/// named edge map then it will write the map value belonging to the edge.
 void writeId(std::ostream& os, const Edge& item) const {
 undir_edgeset_writer.writeId(os, item);
 }
 /// \brief Write the id of the given undirected edge.
 ///
 /// It writes the id of the given undirected edge. If there was written
-/// an "id" named edge map then it will write the map value belongs to
+/// an "id" named edge map then it will write the map value belonging to
 /// the edge.
 void writeId(std::ostream& os, const UndirEdge& item) const {
 undir_edgeset_writer.writeId(os, item);
 }
 AttributeWriter<WriterTraits> attribute_writer;
 };
-/// \brief Write an undirected graph to the output.
+/// \brief Write an undirected multigraph (undirected graph + capacity
-///
+/// map on the edges) to the output.
-/// Write an undirected graph to the output.
+///
+/// Write an undirected multigraph (undirected graph + capacity
+/// map on the edges) to the output.
 /// \param os The output stream.
 /// \param g The graph.
 /// \param capacity The capacity undirected map.
 template<typename Graph, typename CapacityMap>
 void writeUndirGraph(std::ostream& os, const Graph &g,

changeset 1526	8c14aa8f27a2
parent 1435	8e85e6bbefdf
child 1534	b86aad11f842