[Boost-bugs] [Boost C++ Libraries] #8496: Signals2 "reference" documentation inadequate

Subject: [Boost-bugs] [Boost C++ Libraries] #8496: Signals2 "reference" documentation inadequate
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2013-04-25 18:09:30

#8496: Signals2 "reference" documentation inadequate
--------------------------------------------------------------------------+-
 Reporter:  Mike Cowperthwaite <michael.cowperthwaite@…>                  |        Type:  Bugs            
   Status:  new                                                           |   Milestone:  To Be Determined
Component:  None                                                          |     Version:  Boost 1.52.0    
 Severity:  Cosmetic                                                      |    Keywords:                  
--------------------------------------------------------------------------+-
 The reference page for Signals2 does not provide enough information. I
 shouldn't have to to browse the source in order to discover basic details
 of the classes in this library.

 A particular point: the `signal.hpp` listing shows no methods of a
 `signal`.  One needs to browse into `signal.hpp`, then to
 `preprocessed_signal.hpp`, and then to `detail/signal_tempate.hpp`, and
 then search for "connect(" or similar, to actually find the methods of a
 signal.

 I've been using signals for a couple of years, and I only just discovered
 that the `connect()` method (1) takes a `const&slot`, rather than just a
 `slot`, and (2) has a second `position` argument with a default value. I
 knew from reading other documentation that there is a connect_extended()
 method, but no examples of use, requiring me to once again delve down into
 source that is supposed to not be important to the end user -- that's why
 it's in DETAIL.

 The same issues pertain with `connection` and `slot`.

 Further, I am opposed to alphabetical organization of classes. Order them
 by importance: `signal`, `slot`, `connection` should be first.

 I'm only setting this bug's severity to "cosmetic" because the other
 documentation bugs I've found have that setting.

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