Skip to content

Slight issues in sigc::connection intro documentation #88

Closed
@db-src

Description

@db-src

Currently it reads as:

/** Convinience class for safe disconnection.
 * Iterators must not be used beyond the lifetime of the list
 * they work on. A connection object can be created from a
 * slot list iterator and may safely be used to disconnect
 * the referred slot at any time (disconnect()). If the slot
 * has already been destroyed, disconnect() does nothing. empty() or
 * operator bool() can be used to test whether the connection is
 * still active. The connection can be blocked (block(), unblock()).
 *
 * This is possible because the connection object gets notified
 * when the referred slot dies (notify()).
 *
 * @ingroup signal
 */
  • Convinience is a typo!
  • The remainder focuses only on slot iterators and even then is not terribly clear:
    • We may want to first talk about how, separate from slot iterator lifetime issues, sigc::connections can be used to disconnect(), block(), etc. - and only after that mention how those abilities can help avoid issues with slot iterator validity.
    • It should perhaps be "Slot iterators [link to info about accumulators somewhere] must not be used beyond..." or something - currently just opening talking about "Iterators" without further qualification seems liable to confuse users.

Would it be possible to make this more general, clearer about slot iterators, etc.?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions