[2932] Document the notification interface

src/lib/config/ccsession.h

@@ -575,17 +575,55 @@ public:
     /// \param id The id of request as returned by groupRecvMsgAsync.
     void cancelAsyncRecv(const AsyncRecvRequestID& id);
 
+    /// \brief Called when a notification comes
+    ///
+    /// The callback should be exception-free. If it raises an exception,
+    /// it'll leak through the event loop up and probably terminate the
+    /// application.
+    ///
+    /// \param event_name The identification of event type.
+    /// \param params The parameters of the event. This may be NULL
+    ///     pointer in case no parameters were sent with the event.
     typedef boost::function<void (const std::string& event_name,
                                   const data::ConstElementPtr& params)>
         NotificationCallback;
+
+    /// \brief Multiple notification callbacks for the same notification
     typedef std::list<NotificationCallback> NotificationCallbacks;
+
+    /// \brief Mapping from groups to callbacks
     typedef std::map<std::string, NotificationCallbacks>
         SubscribedNotifications;
+
+    /// \brief Identification of single callback
     typedef std::pair<SubscribedNotifications::iterator,
                       NotificationCallbacks::iterator>
         NotificationID;
+
+    /// \brief Subscribe to a notification group
+    ///
+    /// From now on, every notification that is sent to the given group
+    /// triggers the passed callback.
+    ///
+    /// There may be multiple (independent) callbacks for the same channel.
+    /// This one adds a new one, to the end of the chain (the callbacks
+    /// are called in the same order as they were registered).
+    ///
+    /// \param notification_group The channel of notifications.
+    /// \param callback The callback to be added.
+    /// \return ID of the notification callback. It is an opaque ID and can
+    ///     be used to remove this callback.
     NotificationID subscribeNotification(const std::string& notification_group,
                                          const NotificationCallback& callback);
+
+    /// \brief Unsubscribe the callback from its notification group.
+    ///
+    /// Express that the desire for this callback to be executed is no longer
+    /// relevant. All the other callbacks (even for the same notification
+    /// group) are left intact.
+    ///
+    /// \param notification The ID of notification callback returned by
+    ///     subscribeNotification.
     void unsubscribeNotification(const NotificationID& notification);
 
     /// \brief Subscribe to a group