[Boost-bugs] [Boost C++ Libraries] #12764: Improve documentation regarding disposers

Subject: [Boost-bugs] [Boost C++ Libraries] #12764: Improve documentation regarding disposers
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2017-01-16 23:13:00

#12764: Improve documentation regarding disposers
------------------------------+--------------------------
 Reporter:  fdegros@…         |      Owner:  igaztanaga
     Type:  Feature Requests  |     Status:  new
Milestone:  To Be Determined  |  Component:  intrusive
  Version:  Boost 1.63.0      |   Severity:  Optimization
 Keywords:                    |
------------------------------+--------------------------
 The documentation about disposers in intrusive containers could be
 improved.

 Disposers are unusual in the sense that they deal with pointers to nodes
 whereas all the other intrusive container APIs deal with references to
 nodes. This point should be made clearer.

 For example, in:
 http://www.boost.org/doc/libs/1_63_0/doc/html/intrusive/erasing_and_disposing.html


 {{{remove_and_dispose_if}}} will call the "disposer" function object for
 every removed element.

 The documentation should emphasize that the element is passed to the
 disposer function by pointer, and not by reference. It is even more
 important in this example because {{{remove_and_dispose_if}}} also takes a
 predicate function taking elements by reference. So, we have a method
 {{{remove_and_dispose_if}}} taking two callbacks receiving elements in a
 different way: the predicate takes elements by reference, and the disposer
 takes elements by pointer. This is confusing and looks like a gratuitous
 inconsistency. This difference should be better explained, as well as the
 reason why disposers take elements by pointer and not by reference.

 Also in the same page:
 "Note that the disposing function does not need to just destroy the
 object. It can implement any other operation like inserting the remove
 object in another container. Let's see a small example..."

 But the example that follows doesn't show how to insert the removed object
 into another container. It shows how to destroy it with the delete
 operator.

 There is also a typo here. Change "the remove object" to "the removed
 object".

 Finally, this documentation should probably mention
 [http://en.cppreference.com/w/cpp/memory/default_delete

 std::default_delete]. It could be used in the example instead of rolling
 out our own function object calling the {{{delete}}} operator.

-- 
Ticket URL: <https://svn.boost.org/trac/boost/ticket/12764>
Boost C++ Libraries <http://www.boost.org/>
Boost provides free peer-reviewed portable C++ source libraries.