[Boost-bugs] [Boost C++ Libraries] #6437: Documentation bug about ptr_multi_map_adapter::insert(...) return value

Subject: [Boost-bugs] [Boost C++ Libraries] #6437: Documentation bug about ptr_multi_map_adapter::insert(...) return value
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2012-01-23 12:08:39

#6437: Documentation bug about ptr_multi_map_adapter::insert(...) return value
----------------------------------------------------+-----------------------
 Reporter:  augustin <augustin_boost@…>             |       Owner:  nesotto      
     Type:  Bugs                                    |      Status:  new          
Milestone:  To Be Determined                        |   Component:  ptr_container
  Version:  Boost 1.48.0                            |    Severity:  Problem      
 Keywords:                                          |  
----------------------------------------------------+-----------------------
 It seems that the documentation for ptr_multi_map_adatpter is wrong as
 there is a discrepancy with the code. I am a beginner, so if I am wrong,
 please gently explain why.

 http://www.boost.org/doc/libs/1_48_0/libs/ptr_container/doc/ptr_multimap_adapter.html

 shows:
 {{{

     class ptr_multimap_adapter
     {
         // ...
         iterator  insert( key_type& k, T* x );
         template< class U >
         iterator  insert( const key_type&, std::auto_ptr<U> x );
         // ...
      }
 }}}

 However, the source code shows:

 {{{

         std::pair<iterator,bool> insert( key_type& key, mapped_type x )
         {
             return insert_impl( key, x );
         }

         template< class U >
         std::pair<iterator,bool> insert( const key_type& key,
 std::auto_ptr<U> x )
         {
             return insert_impl( key, x.release() );
         }
 }}}

 It seems there is a mismatch between the documentation and the code as to
 the type of the return value (iterator vs. pair).

 The following test code provides an example of what I was trying to do
 after reading the documentation, but obviously that didn't compile:

 {{{
 #include <boost/ptr_container/ptr_map.hpp>
 #include <string>
 #include <utility>

 int main() {
         boost::ptr_map<int, std::string> map;
         boost::ptr_map<int, std::string>::iterator map_it;
         std::string* s = new std::string("one");
         int i = 1;
         //map_it = map.insert(i, s); // Does not compile.
         std::pair< boost::ptr_map<int, std::string>::iterator, bool> ret =
 map.insert(i, s); // This compiles.
 }
 }}}

 How is the code documentation generated? By hand?

 While learning how to use ptr_container, I have often wished there were
 more extensive documentation and examples on how to use ptr_map. If the
 above is indeed a documentation bug, can you use this opportunity to add a
 sample code section on how to create, insert and retrieve elements with a
 ptr_map?

 Thanks.

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