From 778f99798e6c02bdc40fbd6c7cc14e49b929d629 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Tue, 12 Feb 2019 06:03:13 -0800 Subject: [PATCH] [notifier] enhance documentation (#3583) --- src/core/common/notifier.hpp | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/src/core/common/notifier.hpp b/src/core/common/notifier.hpp index 5a6c0bb6f..564ef76be 100644 --- a/src/core/common/notifier.hpp +++ b/src/core/common/notifier.hpp @@ -60,14 +60,23 @@ namespace ot { /** * This class implements the OpenThread Notifier. * - * It can be used to register callbacks to be notified of state or configuration changes within OpenThread. + * It can be used to register callbacks that notify of state or configuration changes within OpenThread. + * + * Two callback models are provided: + * + * - A `Notifier::Callback` object that upon initialization (from its constructor) auto-registers itself with + * the `Notifier`. This model is mainly used by OpenThread core modules. + * + * - A `otStateChangedCallback` callback handler which needs to be explicitly registered with the `Notifier`. This is + * commonly used by external users (provided as an OpenThread public API). Max number of such callbacks that can be + * registered at the same time is specified by `OPENTHREAD_CONFIG_MAX_STATECHANGE_HANDLERS` configuration parameter. * */ class Notifier : public InstanceLocator { public: /** - * This class defines a callback instance that can be registered with the `Notifier`. + * This class defines a `Notifier` callback instance. * */ class Callback : public OwnerLocator @@ -85,7 +94,7 @@ public: typedef void (*Handler)(Callback &aCallback, otChangedFlags aFlags); /** - * This constructor initializes a `Callback` instance + * This constructor initializes a `Callback` instance and registers it with `Notifier`. * * @param[in] aInstance A reference to OpenThread instance. * @param[in] aHandler A function pointer to the callback handler.