Merge pull request #116 from barnou-psee/fix/function-in-namespace

docs/snippets/functions.md

@@ -31,3 +31,40 @@ indent_level: 4
 ::: doxy.animal.function
 name: mEin
 indent_level: 4
+
+## `::: doxy.<project>.namespace.function`
+
+This tag generates full function documentation.
+
+| Parameter   | Description               | Required |
+|-------------|---------------------------|----------|
+| `namespace` | The name of the amespace. | Yes      |
+| `name`      | The name of the function. | Yes      |
+
+
+=== "Tag usage"
+    ```yaml
+    ::: doxy.animal.namespace.function
+        namespace: example
+        name: void some_namespace_function(Animal* animal)
+    ```
+=== "Tag result"
+::: doxy.animal.namespace.function
+namespace: example
+name: void some_namespace_function(Animal* animal)
+indent_level: 4
+
+
+## `::: doxy.<project>.function` error message
+
+=== "Tag usage"
+    ```yaml
+    ::: doxy.animal.namespace.function
+        namespace: example
+        name: void no_function()
+    ```
+=== "Tag result"
+::: doxy.animal.function
+namespace: example
+name: void no_function()
+indent_level: 4

mkdoxy/finder.py

@@ -16,33 +16,47 @@ def _normalize(self, name: str) -> str:
     def listToNames(self, list):
         return [part.name_params for part in list]
 
-    def doxyClass(self, project, className: str):
-        classes = recursive_find(self.doxygen[project].root.children, Kind.CLASS)
-        if classes:
-            for findClass in classes:
-                if findClass.name_long == className:
-                    return findClass
-            return self.listToNames(classes)
+    def _doxyParent(self, project, parent: str, kind: Kind):
+        if not kind.is_parent():
+            return None
+        parents = recursive_find(self.doxygen[project].root.children, kind)
+        if parents:
+            for findParent in parents:
+                if findParent.name_long == parent:
+                    return findParent
+            return self.listToNames(parents)
         return None
 
-    def doxyClassMethod(self, project, className: str, methodName: str):
-        findClass = self.doxyClass(project, className)
-        if findClass:
-            if isinstance(findClass, list):
-                for member in findClass:
-                    if self._normalize(methodName) in self._normalize(member):
+    def _doxyMemberInParent(self, project, parent: str, parentKind: Kind, memberName: str, memberKind: Kind):
+        findParent = self._doxyParent(project, parent, parentKind)
+        if findParent:
+            if isinstance(findParent, list):
+                for member in findParent:
+                    if self._normalize(memberName) in self._normalize(member):
                         return member
-                return findClass
+                return findParent
             else:
-                members = recursive_find(findClass.children, Kind.FUNCTION)
+                members = recursive_find(findParent.children, memberKind)
                 if members:
                     for member in members:
-                        if self._normalize(methodName) in self._normalize(member.name_params):
+                        if self._normalize(memberName) in self._normalize(member.name_params):
                             return member
                     return self.listToNames(members)
                 return None
         return None
 
+    def doxyClass(self, project, className: str):
+        return self._doxyParent(project, className, Kind.CLASS)
+
+    def doxyNamespace(self, project, namespace: str):
+        return self._doxyParent(project, namespace, Kind.NAMESPACE)
+
+    def doxyClassMethod(self, project, className: str, methodName: str):
+        return self._doxyMemberInParent(project, className, Kind.CLASS, methodName, Kind.FUNCTION)
+
+    def doxyNamespaceFunction(self, project, namespace: str, functionName: str):
+        return self._doxyMemberInParent(project, namespace, Kind.NAMESPACE, functionName, Kind.FUNCTION)
+
     def doxyFunction(self, project, functionName: str):
         functions = recursive_find_with_parent(self.doxygen[project].files.children, [Kind.FUNCTION], [Kind.FILE])
         if functions:

mkdoxy/generatorSnippets.py

@@ -42,6 +42,7 @@ def __init__(
         self.doxy_arguments = {
             "code": self.doxyCode,
             "function": self.doxyFunction,
+            "namespace.function": self.doxyNamespaceFunction,
             "class": self.doxyClass,
             "class.method": self.doxyClassMethod,
             "class.list": self.doxyClassList,
@@ -370,6 +371,29 @@ def doxyNamespaceList(self, snippet, project: str, config):
         self._setLinkPrefixNodes(nodes, self.pageUrlPrefix + project + "/")
         return self.generatorBase[project].namespaces(nodes, config)
 
+    def doxyNamespaceFunction(self, snippet, project: str, config):
+        errorMsg = self.checkConfig(snippet, project, config, ["namespace", "name"])
+        if errorMsg:
+            return errorMsg
+
+        node = self.finder.doxyNamespaceFunction(project, config.get("namespace"), config.get("name"))
+        if node is None:
+            return self.doxyNodeIsNone(project, config, snippet)
+
+        if isinstance(node, Node):
+            self._setLinkPrefixNode(node, self.pageUrlPrefix + project + "/")
+            return self.generatorBase[project].function(node, config)
+        return self.doxyError(
+            project,
+            config,
+            "Incorrect namespace function configuration",
+            f"Did not find Namespace with name: `{config.get('namespace')}` and function: `{config.get('name')}`",
+            "Available classes and methods:",
+            "\n".join(node),
+            "yaml",
+            snippet,
+        )
+
     def doxyFileList(self, snippet, project: str, config):
         errorMsg = self.checkConfig(snippet, project, config, [])
         if errorMsg: