Some small docstring tweaks

Rowan · Wiebe Cazemier
1 parent 541ef599
Showing 2 changed files with 9 additions and 5 deletions
acltree.cpp
acltree.h
@@ -202,13 +202,13 @@ void AclTree::findPermissionRecursive(std::vector&lt;std::string&gt;::const_iterator c
 }
  
 /**
- * @brief AclTree::findPermission tests permissions as loaded from the Mosquitto acl_file.
+ * @brief AclTree::findPermission tests permissions as loaded from the Mosquitto-compatible acl_file.
  * @param subtopicsPublish
- * @param access
- * @param username
+ * @param access Whether to test read access or write access (`AclGrant::Read` or `AclGrant::Write` respectively).
+ * @param username The user to test permission for.
  * @return
  *
- * It's behaves like Mosquitto's ACL file. Some of that behavior is a bit limited, but sticking to it for compatability:
+ * It behaves like Mosquitto's ACL file. Some of that behavior is a bit limited, but sticking to it for compatability:
  *
  * - If your user is authenticated, there must a user specific definition for that user; it won't fall back on anonymous ACLs.
  * - You can't combine ACLs, like 'all clients read bla/#' and add 'user john readwrite bla/#. User specific ACLs don't add
@@ -26,12 +26,16 @@ enum class AclTopicType
  
 AclGrant stringToAclGrant(const std::string &s);
  
+/**
+ * @brief Permissions for an MQTT topic path is a tree of `AclNode`s. Topic paths are broken up and matched down the tree. A '#' wildcard will match
+ * all following subtopics, so therefore '#' is a 'grant', not a 'child'.
+ */
 class AclNode
 {
     bool empty = false;
  
     std::unordered_map<std::string, std::unique_ptr<AclNode>> children;
-    std::unique_ptr<AclNode> childrenPlus;
+    std::unique_ptr<AclNode> childrenPlus; // The + sign in MQTT represents a single-level wildcard
  
     std::vector<AclGrant> grants;
     std::vector<AclGrant> grantsPound; // The # sign. This is short-hand for avoiding one memory access though a layer of std::unique_ptr<AclNode>