# HG changeset patch # User Peter Kovacs # Date 2008-11-04 21:37:59 # Node ID f58410582b9bac22c553618b60d5fce2ad4e89ab # Parent 75cf49ce539059c67130b03592325fcbd5e4f96c Doc improvements for the graph related tools in lemon/bits diff --git a/lemon/bits/alteration_notifier.h b/lemon/bits/alteration_notifier.h --- a/lemon/bits/alteration_notifier.h +++ b/lemon/bits/alteration_notifier.h @@ -35,61 +35,62 @@ // \brief Notifier class to notify observes about alterations in // a container. // - // The simple graph's can be refered as two containers, one node container - // and one edge container. But they are not standard containers they - // does not store values directly they are just key continars for more - // value containers which are the node and edge maps. + // The simple graphs can be refered as two containers: a node container + // and an edge container. But they do not store values directly, they + // are just key continars for more value containers, which are the + // node and edge maps. // - // The graph's node and edge sets can be changed as we add or erase + // The node and edge sets of the graphs can be changed as we add or erase // nodes and edges in the graph. LEMON would like to handle easily // that the node and edge maps should contain values for all nodes or // edges. If we want to check on every indicing if the map contains // the current indicing key that cause a drawback in the performance - // in the library. We use another solution we notify all maps about + // in the library. We use another solution: we notify all maps about // an alteration in the graph, which cause only drawback on the // alteration of the graph. // - // This class provides an interface to the container. The \e first() and \e - // next() member functions make possible to iterate on the keys of the - // container. The \e id() function returns an integer id for each key. - // The \e maxId() function gives back an upper bound of the ids. + // This class provides an interface to a node or edge container. + // The first() and next() member functions make possible + // to iterate on the keys of the container. + // The id() function returns an integer id for each key. + // The maxId() function gives back an upper bound of the ids. // // For the proper functonality of this class, we should notify it - // about each alteration in the container. The alterations have four type - // as \e add(), \e erase(), \e build() and \e clear(). The \e add() and - // \e erase() signals that only one or few items added or erased to or - // from the graph. If all items are erased from the graph or from an empty - // graph a new graph is builded then it can be signaled with the + // about each alteration in the container. The alterations have four type: + // add(), erase(), build() and clear(). The add() and + // erase() signal that only one or few items added or erased to or + // from the graph. If all items are erased from the graph or if a new graph + // is built from an empty graph, then it can be signaled with the // clear() and build() members. Important rule that if we erase items - // from graph we should first signal the alteration and after that erase + // from graphs we should first signal the alteration and after that erase // them from the container, on the other way on item addition we should // first extend the container and just after that signal the alteration. // // The alteration can be observed with a class inherited from the - // \e ObserverBase nested class. The signals can be handled with + // ObserverBase nested class. The signals can be handled with // overriding the virtual functions defined in the base class. The // observer base can be attached to the notifier with the - // \e attach() member and can be detached with detach() function. The + // attach() member and can be detached with detach() function. The // alteration handlers should not call any function which signals // an other alteration in the same notifier and should not // detach any observer from the notifier. // - // Alteration observers try to be exception safe. If an \e add() or - // a \e clear() function throws an exception then the remaining + // Alteration observers try to be exception safe. If an add() or + // a clear() function throws an exception then the remaining // observeres will not be notified and the fulfilled additions will - // be rolled back by calling the \e erase() or \e clear() - // functions. Thence the \e erase() and \e clear() should not throw - // exception. Actullay, it can be throw only \ref ImmediateDetach - // exception which detach the observer from the notifier. + // be rolled back by calling the erase() or clear() functions. + // Hence erase() and clear() should not throw exception. + // Actullay, they can throw only \ref ImmediateDetach exception, + // which detach the observer from the notifier. // - // There are some place when the alteration observing is not completly + // There are some cases, when the alteration observing is not completly // reliable. If we want to carry out the node degree in the graph - // as in the \ref InDegMap and we use the reverseEdge that cause + // as in the \ref InDegMap and we use the reverseArc(), then it cause // unreliable functionality. Because the alteration observing signals - // only erasing and adding but not the reversing it will stores bad - // degrees. The sub graph adaptors cannot signal the alterations because - // just a setting in the filter map can modify the graph and this cannot - // be watched in any way. + // only erasing and adding but not the reversing, it will stores bad + // degrees. Apart form that the subgraph adaptors cannot even signal + // the alterations because just a setting in the filter map can modify + // the graph and this cannot be watched in any way. // // \param _Container The container which is observed. // \param _Item The item type which is obserbved. @@ -103,13 +104,13 @@ typedef _Container Container; typedef _Item Item; - // \brief Exception which can be called from \e clear() and - // \e erase(). + // \brief Exception which can be called from clear() and + // erase(). // - // From the \e clear() and \e erase() function only this + // From the clear() and erase() function only this // exception is allowed to throw. The exception immediatly // detaches the current observer from the notifier. Because the - // \e clear() and \e erase() should not throw other exceptions + // clear() and erase() should not throw other exceptions // it can be used to invalidate the observer. struct ImmediateDetach {}; @@ -121,8 +122,7 @@ // // The observer interface contains some pure virtual functions // to override. The add() and erase() functions are - // to notify the oberver when one item is added or - // erased. + // to notify the oberver when one item is added or erased. // // The build() and clear() members are to notify the observer // about the container is built from an empty container or diff --git a/lemon/bits/array_map.h b/lemon/bits/array_map.h --- a/lemon/bits/array_map.h +++ b/lemon/bits/array_map.h @@ -36,25 +36,24 @@ // // \brief Graph map based on the array storage. // - // The ArrayMap template class is graph map structure what - // automatically updates the map when a key is added to or erased from - // the map. This map uses the allocators to implement - // the container functionality. + // The ArrayMap template class is graph map structure that automatically + // updates the map when a key is added to or erased from the graph. + // This map uses the allocators to implement the container functionality. // - // The template parameters are the Graph the current Item type and + // The template parameters are the Graph, the current Item type and // the Value type of the map. template class ArrayMap : public ItemSetTraits<_Graph, _Item>::ItemNotifier::ObserverBase { public: - // The graph type of the maps. + // The graph type. typedef _Graph Graph; - // The item type of the map. + // The item type. typedef _Item Item; // The reference map tag. typedef True ReferenceMapTag; - // The key type of the maps. + // The key type of the map. typedef _Item Key; // The value type of the map. typedef _Value Value; @@ -200,7 +199,7 @@ // \brief Adds a new key to the map. // - // It adds a new key to the map. It called by the observer notifier + // It adds a new key to the map. It is called by the observer notifier // and it overrides the add() member function of the observer base. virtual void add(const Key& key) { Notifier* nf = Parent::notifier(); @@ -228,7 +227,7 @@ // \brief Adds more new keys to the map. // - // It adds more new keys to the map. It called by the observer notifier + // It adds more new keys to the map. It is called by the observer notifier // and it overrides the add() member function of the observer base. virtual void add(const std::vector& keys) { Notifier* nf = Parent::notifier(); @@ -272,7 +271,7 @@ // \brief Erase a key from the map. // - // Erase a key from the map. It called by the observer notifier + // Erase a key from the map. It is called by the observer notifier // and it overrides the erase() member function of the observer base. virtual void erase(const Key& key) { int id = Parent::notifier()->id(key); @@ -281,7 +280,7 @@ // \brief Erase more keys from the map. // - // Erase more keys from the map. It called by the observer notifier + // Erase more keys from the map. It is called by the observer notifier // and it overrides the erase() member function of the observer base. virtual void erase(const std::vector& keys) { for (int i = 0; i < int(keys.size()); ++i) { @@ -290,9 +289,9 @@ } } - // \brief Buildes the map. + // \brief Builds the map. // - // It buildes the map. It called by the observer notifier + // It builds the map. It is called by the observer notifier // and it overrides the build() member function of the observer base. virtual void build() { Notifier* nf = Parent::notifier(); @@ -306,7 +305,7 @@ // \brief Clear the map. // - // It erase all items from the map. It called by the observer notifier + // It erase all items from the map. It is called by the observer notifier // and it overrides the clear() member function of the observer base. virtual void clear() { Notifier* nf = Parent::notifier(); diff --git a/lemon/bits/base_extender.h b/lemon/bits/base_extender.h --- a/lemon/bits/base_extender.h +++ b/lemon/bits/base_extender.h @@ -30,7 +30,7 @@ //\ingroup digraphbits //\file -//\brief Extenders for the digraph types +//\brief Extenders for the graph types namespace lemon { // \ingroup digraphbits diff --git a/lemon/bits/graph_extender.h b/lemon/bits/graph_extender.h --- a/lemon/bits/graph_extender.h +++ b/lemon/bits/graph_extender.h @@ -29,12 +29,12 @@ //\ingroup graphbits //\file -//\brief Extenders for the digraph types +//\brief Extenders for the graph types namespace lemon { // \ingroup graphbits // - // \brief Extender for the Digraphs + // \brief Extender for the digraph implementations template class DigraphExtender : public Base { public: diff --git a/lemon/bits/vector_map.h b/lemon/bits/vector_map.h --- a/lemon/bits/vector_map.h +++ b/lemon/bits/vector_map.h @@ -38,9 +38,9 @@ // // \brief Graph map based on the std::vector storage. // - // The VectorMap template class is graph map structure what - // automatically updates the map when a key is added to or erased from - // the map. This map type uses the std::vector to store the values. + // The VectorMap template class is graph map structure that automatically + // updates the map when a key is added to or erased from the graph. + // This map type uses std::vector to store the values. // // \tparam _Graph The graph this map is attached to. // \tparam _Item The item type of the graph items. @@ -169,7 +169,7 @@ // \brief Adds a new key to the map. // - // It adds a new key to the map. It called by the observer notifier + // It adds a new key to the map. It is called by the observer notifier // and it overrides the add() member function of the observer base. virtual void add(const Key& key) { int id = Parent::notifier()->id(key); @@ -180,7 +180,7 @@ // \brief Adds more new keys to the map. // - // It adds more new keys to the map. It called by the observer notifier + // It adds more new keys to the map. It is called by the observer notifier // and it overrides the add() member function of the observer base. virtual void add(const std::vector& keys) { int max = container.size() - 1; @@ -195,7 +195,7 @@ // \brief Erase a key from the map. // - // Erase a key from the map. It called by the observer notifier + // Erase a key from the map. It is called by the observer notifier // and it overrides the erase() member function of the observer base. virtual void erase(const Key& key) { container[Parent::notifier()->id(key)] = Value(); @@ -203,7 +203,7 @@ // \brief Erase more keys from the map. // - // Erase more keys from the map. It called by the observer notifier + // It erases more keys from the map. It is called by the observer notifier // and it overrides the erase() member function of the observer base. virtual void erase(const std::vector& keys) { for (int i = 0; i < int(keys.size()); ++i) { @@ -211,9 +211,9 @@ } } - // \brief Buildes the map. + // \brief Build the map. // - // It buildes the map. It called by the observer notifier + // It builds the map. It is called by the observer notifier // and it overrides the build() member function of the observer base. virtual void build() { int size = Parent::notifier()->maxId() + 1; @@ -223,7 +223,7 @@ // \brief Clear the map. // - // It erase all items from the map. It called by the observer notifier + // It erases all items from the map. It is called by the observer notifier // and it overrides the clear() member function of the observer base. virtual void clear() { container.clear();