Doc improvements for the graph related tools in lemon/bits
authorPeter Kovacs <kpeter@inf.elte.hu>
Tue, 04 Nov 2008 21:37:59 +0100
changeset 373f58410582b9b
parent 372 75cf49ce5390
child 374 51597950d0fe
Doc improvements for the graph related tools in lemon/bits
lemon/bits/alteration_notifier.h
lemon/bits/array_map.h
lemon/bits/base_extender.h
lemon/bits/graph_extender.h
lemon/bits/vector_map.h
     1.1 --- a/lemon/bits/alteration_notifier.h	Tue Nov 04 21:36:46 2008 +0100
     1.2 +++ b/lemon/bits/alteration_notifier.h	Tue Nov 04 21:37:59 2008 +0100
     1.3 @@ -35,61 +35,62 @@
     1.4    // \brief Notifier class to notify observes about alterations in
     1.5    // a container.
     1.6    //
     1.7 -  // The simple graph's can be refered as two containers, one node container
     1.8 -  // and one edge container. But they are not standard containers they
     1.9 -  // does not store values directly they are just key continars for more
    1.10 -  // value containers which are the node and edge maps.
    1.11 +  // The simple graphs can be refered as two containers: a node container
    1.12 +  // and an edge container. But they do not store values directly, they
    1.13 +  // are just key continars for more value containers, which are the
    1.14 +  // node and edge maps.
    1.15    //
    1.16 -  // The graph's node and edge sets can be changed as we add or erase
    1.17 +  // The node and edge sets of the graphs can be changed as we add or erase
    1.18    // nodes and edges in the graph. LEMON would like to handle easily
    1.19    // that the node and edge maps should contain values for all nodes or
    1.20    // edges. If we want to check on every indicing if the map contains
    1.21    // the current indicing key that cause a drawback in the performance
    1.22 -  // in the library. We use another solution we notify all maps about
    1.23 +  // in the library. We use another solution: we notify all maps about
    1.24    // an alteration in the graph, which cause only drawback on the
    1.25    // alteration of the graph.
    1.26    //
    1.27 -  // This class provides an interface to the container. The \e first() and \e
    1.28 -  // next() member functions make possible to iterate on the keys of the
    1.29 -  // container. The \e id() function returns an integer id for each key.
    1.30 -  // The \e maxId() function gives back an upper bound of the ids.
    1.31 +  // This class provides an interface to a node or edge container.
    1.32 +  // The first() and next() member functions make possible
    1.33 +  // to iterate on the keys of the container.
    1.34 +  // The id() function returns an integer id for each key.
    1.35 +  // The maxId() function gives back an upper bound of the ids.
    1.36    //
    1.37    // For the proper functonality of this class, we should notify it
    1.38 -  // about each alteration in the container. The alterations have four type
    1.39 -  // as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
    1.40 -  // \e erase() signals that only one or few items added or erased to or
    1.41 -  // from the graph. If all items are erased from the graph or from an empty
    1.42 -  // graph a new graph is builded then it can be signaled with the
    1.43 +  // about each alteration in the container. The alterations have four type:
    1.44 +  // add(), erase(), build() and clear(). The add() and
    1.45 +  // erase() signal that only one or few items added or erased to or
    1.46 +  // from the graph. If all items are erased from the graph or if a new graph
    1.47 +  // is built from an empty graph, then it can be signaled with the
    1.48    // clear() and build() members. Important rule that if we erase items
    1.49 -  // from graph we should first signal the alteration and after that erase
    1.50 +  // from graphs we should first signal the alteration and after that erase
    1.51    // them from the container, on the other way on item addition we should
    1.52    // first extend the container and just after that signal the alteration.
    1.53    //
    1.54    // The alteration can be observed with a class inherited from the
    1.55 -  // \e ObserverBase nested class. The signals can be handled with
    1.56 +  // ObserverBase nested class. The signals can be handled with
    1.57    // overriding the virtual functions defined in the base class.  The
    1.58    // observer base can be attached to the notifier with the
    1.59 -  // \e attach() member and can be detached with detach() function. The
    1.60 +  // attach() member and can be detached with detach() function. The
    1.61    // alteration handlers should not call any function which signals
    1.62    // an other alteration in the same notifier and should not
    1.63    // detach any observer from the notifier.
    1.64    //
    1.65 -  // Alteration observers try to be exception safe. If an \e add() or
    1.66 -  // a \e clear() function throws an exception then the remaining
    1.67 +  // Alteration observers try to be exception safe. If an add() or
    1.68 +  // a clear() function throws an exception then the remaining
    1.69    // observeres will not be notified and the fulfilled additions will
    1.70 -  // be rolled back by calling the \e erase() or \e clear()
    1.71 -  // functions. Thence the \e erase() and \e clear() should not throw
    1.72 -  // exception. Actullay, it can be throw only \ref ImmediateDetach
    1.73 -  // exception which detach the observer from the notifier.
    1.74 +  // be rolled back by calling the erase() or clear() functions.
    1.75 +  // Hence erase() and clear() should not throw exception.
    1.76 +  // Actullay, they can throw only \ref ImmediateDetach exception,
    1.77 +  // which detach the observer from the notifier.
    1.78    //
    1.79 -  // There are some place when the alteration observing is not completly
    1.80 +  // There are some cases, when the alteration observing is not completly
    1.81    // reliable. If we want to carry out the node degree in the graph
    1.82 -  // as in the \ref InDegMap and we use the reverseEdge that cause
    1.83 +  // as in the \ref InDegMap and we use the reverseArc(), then it cause
    1.84    // unreliable functionality. Because the alteration observing signals
    1.85 -  // only erasing and adding but not the reversing it will stores bad
    1.86 -  // degrees. The sub graph adaptors cannot signal the alterations because
    1.87 -  // just a setting in the filter map can modify the graph and this cannot
    1.88 -  // be watched in any way.
    1.89 +  // only erasing and adding but not the reversing, it will stores bad
    1.90 +  // degrees. Apart form that the subgraph adaptors cannot even signal
    1.91 +  // the alterations because just a setting in the filter map can modify
    1.92 +  // the graph and this cannot be watched in any way.
    1.93    //
    1.94    // \param _Container The container which is observed.
    1.95    // \param _Item The item type which is obserbved.
    1.96 @@ -103,13 +104,13 @@
    1.97      typedef _Container Container;
    1.98      typedef _Item Item;
    1.99  
   1.100 -    // \brief Exception which can be called from \e clear() and
   1.101 -    // \e erase().
   1.102 +    // \brief Exception which can be called from clear() and
   1.103 +    // erase().
   1.104      //
   1.105 -    // From the \e clear() and \e erase() function only this
   1.106 +    // From the clear() and erase() function only this
   1.107      // exception is allowed to throw. The exception immediatly
   1.108      // detaches the current observer from the notifier. Because the
   1.109 -    // \e clear() and \e erase() should not throw other exceptions
   1.110 +    // clear() and erase() should not throw other exceptions
   1.111      // it can be used to invalidate the observer.
   1.112      struct ImmediateDetach {};
   1.113  
   1.114 @@ -121,8 +122,7 @@
   1.115      //
   1.116      // The observer interface contains some pure virtual functions
   1.117      // to override. The add() and erase() functions are
   1.118 -    // to notify the oberver when one item is added or
   1.119 -    // erased.
   1.120 +    // to notify the oberver when one item is added or erased.
   1.121      //
   1.122      // The build() and clear() members are to notify the observer
   1.123      // about the container is built from an empty container or
     2.1 --- a/lemon/bits/array_map.h	Tue Nov 04 21:36:46 2008 +0100
     2.2 +++ b/lemon/bits/array_map.h	Tue Nov 04 21:37:59 2008 +0100
     2.3 @@ -36,25 +36,24 @@
     2.4    //
     2.5    // \brief Graph map based on the array storage.
     2.6    //
     2.7 -  // The ArrayMap template class is graph map structure what
     2.8 -  // automatically updates the map when a key is added to or erased from
     2.9 -  // the map. This map uses the allocators to implement
    2.10 -  // the container functionality.
    2.11 +  // The ArrayMap template class is graph map structure that automatically
    2.12 +  // updates the map when a key is added to or erased from the graph.
    2.13 +  // This map uses the allocators to implement the container functionality.
    2.14    //
    2.15 -  // The template parameters are the Graph the current Item type and
    2.16 +  // The template parameters are the Graph, the current Item type and
    2.17    // the Value type of the map.
    2.18    template <typename _Graph, typename _Item, typename _Value>
    2.19    class ArrayMap
    2.20      : public ItemSetTraits<_Graph, _Item>::ItemNotifier::ObserverBase {
    2.21    public:
    2.22 -    // The graph type of the maps.
    2.23 +    // The graph type.
    2.24      typedef _Graph Graph;
    2.25 -    // The item type of the map.
    2.26 +    // The item type.
    2.27      typedef _Item Item;
    2.28      // The reference map tag.
    2.29      typedef True ReferenceMapTag;
    2.30  
    2.31 -    // The key type of the maps.
    2.32 +    // The key type of the map.
    2.33      typedef _Item Key;
    2.34      // The value type of the map.
    2.35      typedef _Value Value;
    2.36 @@ -200,7 +199,7 @@
    2.37  
    2.38      // \brief Adds a new key to the map.
    2.39      //
    2.40 -    // It adds a new key to the map. It called by the observer notifier
    2.41 +    // It adds a new key to the map. It is called by the observer notifier
    2.42      // and it overrides the add() member function of the observer base.
    2.43      virtual void add(const Key& key) {
    2.44        Notifier* nf = Parent::notifier();
    2.45 @@ -228,7 +227,7 @@
    2.46  
    2.47      // \brief Adds more new keys to the map.
    2.48      //
    2.49 -    // It adds more new keys to the map. It called by the observer notifier
    2.50 +    // It adds more new keys to the map. It is called by the observer notifier
    2.51      // and it overrides the add() member function of the observer base.
    2.52      virtual void add(const std::vector<Key>& keys) {
    2.53        Notifier* nf = Parent::notifier();
    2.54 @@ -272,7 +271,7 @@
    2.55  
    2.56      // \brief Erase a key from the map.
    2.57      //
    2.58 -    // Erase a key from the map. It called by the observer notifier
    2.59 +    // Erase a key from the map. It is called by the observer notifier
    2.60      // and it overrides the erase() member function of the observer base.
    2.61      virtual void erase(const Key& key) {
    2.62        int id = Parent::notifier()->id(key);
    2.63 @@ -281,7 +280,7 @@
    2.64  
    2.65      // \brief Erase more keys from the map.
    2.66      //
    2.67 -    // Erase more keys from the map. It called by the observer notifier
    2.68 +    // Erase more keys from the map. It is called by the observer notifier
    2.69      // and it overrides the erase() member function of the observer base.
    2.70      virtual void erase(const std::vector<Key>& keys) {
    2.71        for (int i = 0; i < int(keys.size()); ++i) {
    2.72 @@ -290,9 +289,9 @@
    2.73        }
    2.74      }
    2.75  
    2.76 -    // \brief Buildes the map.
    2.77 +    // \brief Builds the map.
    2.78      //
    2.79 -    // It buildes the map. It called by the observer notifier
    2.80 +    // It builds the map. It is called by the observer notifier
    2.81      // and it overrides the build() member function of the observer base.
    2.82      virtual void build() {
    2.83        Notifier* nf = Parent::notifier();
    2.84 @@ -306,7 +305,7 @@
    2.85  
    2.86      // \brief Clear the map.
    2.87      //
    2.88 -    // It erase all items from the map. It called by the observer notifier
    2.89 +    // It erase all items from the map. It is called by the observer notifier
    2.90      // and it overrides the clear() member function of the observer base.
    2.91      virtual void clear() {
    2.92        Notifier* nf = Parent::notifier();
     3.1 --- a/lemon/bits/base_extender.h	Tue Nov 04 21:36:46 2008 +0100
     3.2 +++ b/lemon/bits/base_extender.h	Tue Nov 04 21:37:59 2008 +0100
     3.3 @@ -30,7 +30,7 @@
     3.4  
     3.5  //\ingroup digraphbits
     3.6  //\file
     3.7 -//\brief Extenders for the digraph types
     3.8 +//\brief Extenders for the graph types
     3.9  namespace lemon {
    3.10  
    3.11    // \ingroup digraphbits
     4.1 --- a/lemon/bits/graph_extender.h	Tue Nov 04 21:36:46 2008 +0100
     4.2 +++ b/lemon/bits/graph_extender.h	Tue Nov 04 21:37:59 2008 +0100
     4.3 @@ -29,12 +29,12 @@
     4.4  
     4.5  //\ingroup graphbits
     4.6  //\file
     4.7 -//\brief Extenders for the digraph types
     4.8 +//\brief Extenders for the graph types
     4.9  namespace lemon {
    4.10  
    4.11    // \ingroup graphbits
    4.12    //
    4.13 -  // \brief Extender for the Digraphs
    4.14 +  // \brief Extender for the digraph implementations
    4.15    template <typename Base>
    4.16    class DigraphExtender : public Base {
    4.17    public:
     5.1 --- a/lemon/bits/vector_map.h	Tue Nov 04 21:36:46 2008 +0100
     5.2 +++ b/lemon/bits/vector_map.h	Tue Nov 04 21:37:59 2008 +0100
     5.3 @@ -38,9 +38,9 @@
     5.4    //
     5.5    // \brief Graph map based on the std::vector storage.
     5.6    //
     5.7 -  // The VectorMap template class is graph map structure what
     5.8 -  // automatically updates the map when a key is added to or erased from
     5.9 -  // the map. This map type uses the std::vector to store the values.
    5.10 +  // The VectorMap template class is graph map structure that automatically
    5.11 +  // updates the map when a key is added to or erased from the graph.
    5.12 +  // This map type uses std::vector to store the values.
    5.13    //
    5.14    // \tparam _Graph The graph this map is attached to.
    5.15    // \tparam _Item The item type of the graph items.
    5.16 @@ -169,7 +169,7 @@
    5.17  
    5.18      // \brief Adds a new key to the map.
    5.19      //
    5.20 -    // It adds a new key to the map. It called by the observer notifier
    5.21 +    // It adds a new key to the map. It is called by the observer notifier
    5.22      // and it overrides the add() member function of the observer base.
    5.23      virtual void add(const Key& key) {
    5.24        int id = Parent::notifier()->id(key);
    5.25 @@ -180,7 +180,7 @@
    5.26  
    5.27      // \brief Adds more new keys to the map.
    5.28      //
    5.29 -    // It adds more new keys to the map. It called by the observer notifier
    5.30 +    // It adds more new keys to the map. It is called by the observer notifier
    5.31      // and it overrides the add() member function of the observer base.
    5.32      virtual void add(const std::vector<Key>& keys) {
    5.33        int max = container.size() - 1;
    5.34 @@ -195,7 +195,7 @@
    5.35  
    5.36      // \brief Erase a key from the map.
    5.37      //
    5.38 -    // Erase a key from the map. It called by the observer notifier
    5.39 +    // Erase a key from the map. It is called by the observer notifier
    5.40      // and it overrides the erase() member function of the observer base.
    5.41      virtual void erase(const Key& key) {
    5.42        container[Parent::notifier()->id(key)] = Value();
    5.43 @@ -203,7 +203,7 @@
    5.44  
    5.45      // \brief Erase more keys from the map.
    5.46      //
    5.47 -    // Erase more keys from the map. It called by the observer notifier
    5.48 +    // It erases more keys from the map. It is called by the observer notifier
    5.49      // and it overrides the erase() member function of the observer base.
    5.50      virtual void erase(const std::vector<Key>& keys) {
    5.51        for (int i = 0; i < int(keys.size()); ++i) {
    5.52 @@ -211,9 +211,9 @@
    5.53        }
    5.54      }
    5.55  
    5.56 -    // \brief Buildes the map.
    5.57 +    // \brief Build the map.
    5.58      //
    5.59 -    // It buildes the map. It called by the observer notifier
    5.60 +    // It builds the map. It is called by the observer notifier
    5.61      // and it overrides the build() member function of the observer base.
    5.62      virtual void build() {
    5.63        int size = Parent::notifier()->maxId() + 1;
    5.64 @@ -223,7 +223,7 @@
    5.65  
    5.66      // \brief Clear the map.
    5.67      //
    5.68 -    // It erase all items from the map. It called by the observer notifier
    5.69 +    // It erases all items from the map. It is called by the observer notifier
    5.70      // and it overrides the clear() member function of the observer base.
    5.71      virtual void clear() {
    5.72        container.clear();