diff --git a/include/znc/Modules.h b/include/znc/Modules.h
index a250c7b2..aca782a9 100644
--- a/include/znc/Modules.h
+++ b/include/znc/Modules.h
@@ -1012,6 +1012,8 @@ class CModule {
     virtual EModRet OnTopic(CNick& Nick, CChan& Channel, CString& sTopic);
 
     /** Called for every CAP received via CAP LS from server.
+     *  If you need to also advertise the cap to clients, use
+     *  AddServerDependentCapability() instead.
      *  @param sCap capability supported by server.
      *  @return true if your module supports this CAP and
      *          needs to turn it on with CAP REQ.
@@ -1020,6 +1022,8 @@ class CModule {
     /** Called for every CAP received via CAP LS from server.
      *  By default just calls OnServerCapAvailable() without sValue, so
      *  overriding one of the two is enough.
+     *  If you need to also advertise the cap to clients, use
+     *  AddServerDependentCapability() instead.
      *  @param sCap capability name supported by server.
      *  @param sValue value.
      *  @return true if your module supports this CAP and
@@ -1028,6 +1032,8 @@ class CModule {
     virtual bool OnServerCap302Available(const CString& sCap, const CString& sValue);
     /** Called for every CAP accepted or rejected by server
      *  (with CAP ACK or CAP NAK after our CAP REQ).
+     *  If you need to also advertise the cap to clients, use
+     *  AddServerDependentCapability() instead.
      *  @param sCap capability accepted/rejected by server.
      *  @param bSuccess true if capability was accepted, false if rejected.
      */
@@ -1312,11 +1318,25 @@ class CModule {
     virtual void OnClientDetached();
 
 #ifndef SWIG
+    /** Simple API to support client capabilities which depend on server to support that capability.
+     *  It is built on top of other CAP related API, but removes boilerplate,
+     *  and handles some tricky cases related to cap-notify and JumpNetwork. To
+     *  use, create a subclass of CCapability, and pass to this function; it
+     *  will automatically set the module pointer, then call the callbacks to
+     *  notify you when server and client accepted support of the capability, or
+     *  stopped supporting it. Note that it's not a strict toggle: e.g. sometimes
+     *  client will disable the cap even when it was already disabled for that
+     *  client. If you want to mix this function with other CAP callbacks in the
+     *  same module, in the overridden functions you'll need to explicitly call
+     *  the function from the base class CModule.
+     */
     void AddServerDependentCapability(const CString& sName, std::unique_ptr<CCapability> pCap);
 #endif
 
     /** Called when a client told us CAP LS. Use ssCaps.insert("cap-name")
      *  for announcing capabilities which your module supports.
+     *  If you need to adverite the cap to clients only when it's also supported
+     *  by the server, use AddServerDependentCapability() instead.
      *  @param pClient The client which requested the list.
      *  @param ssCaps set of caps which will be sent to client.
      */
@@ -1330,6 +1350,8 @@ class CModule {
     virtual bool IsClientCapSupported(CClient* pClient, const CString& sCap,
                                       bool bState);
     /** Called when we actually need to turn a capability on or off for a client.
+     *  If you need to adverite the cap to clients only when it's also supported
+     *  by the server, use AddServerDependentCapability() instead.
      *  If implementing a custom capability, make sure to call
      *  pClient->SetTagSupport("tag-name", bState) for each tag that the
      *  capability provides.