Signals2 "reference" documentation inadequate

[Mike Cowperthwaite <michael.cowperthwaite@…>]

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.

[fmh6jj@…]

Replying to Mike Cowperthwaite <michael.cowperthwaite@…>:

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.

No, you don't need to do that. See:

http://www.boost.org/doc/libs/1_53_0/doc/html/boost/signals2/signal.html

It's a little unintuitive to find the proper link from the reference page, but that's an issue with boostbook.

[Frank Mori Hess]

No further response from submitter, closing.