Add doxygen format support (#272)

NilsJPWerner · Apr 1, 2024 · 9c6ed72 · 9c6ed72
1 parent f7bc9f4
commit 9c6ed72
Show file tree

Hide file tree

Showing 6 changed files with 100 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+-   Added doxygen format support ([#120](https://github.com/NilsJPWerner/autoDocstring/issues/120)) (@daluar @PhilipNelson5)
+
 [All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.6.1...master)
 
 ## [0.6.1](https://github.com/NilsJPWerner/autoDocstring/tree/v0.6.1) - 2022-02-15

diff --git a/README.md b/README.md
@@ -20,12 +20,13 @@ Visual Studio Code extension to quickly generate docstrings for python functions
 
 To turn off type generation in docstrings use the `-notypes` template of the desired format. The docBlockr format is a typed version of PEP0257.
 
+-   [docBlockr](docs/docblockr.md)
+-   [doxygen](docs/doxygen.md)
 -   [google](docs/google.md)
--   [sphinx](docs/sphinx.md)
 -   [numpy](docs/numpy.md)
--   [docBlockr](docs/docblockr.md)
 -   [one-line-sphinx](docs/one-line-sphinx.md)
 -   [pep257](docs/pep257.md)
+-   [sphinx](docs/sphinx.md)
 
 ## Usage
 

diff --git a/docs/doxygen.md b/docs/doxygen.md
@@ -0,0 +1,19 @@
+# Doxygen Docstring Format
+
+```python
+def abc(a: int, c = [1,2]):
+    """!
+    @brief _summary_
+
+    @param a (int): _description_
+    @param c (list, optional): _description_. Defaults to [1,2].
+
+    @return (_type_): _description_
+
+    @exception AssertionError: _description_
+    """
+    if a > 10:
+        raise AssertionError("a is more than 10")
+
+    return c
+```
diff --git a/package.json b/package.json
@@ -24,14 +24,15 @@
     "keywords": [
         "python",
         "docstring",
-        "google",
-        "numpy",
-        "sphinx",
         "generator",
         "autodocstring",
-        "docblockr",
         "documentation",
-        "pydocstring"
+        "pydocstring",
+        "docblockr",
+        "doxygen",
+        "google",
+        "numpy",
+        "sphinx"
     ],
     "galleryBanner": {},
     "engines": {
@@ -75,14 +76,16 @@
                     "default": "google",
                     "enum": [
                         "docblockr",
-                        "pep257",
+                        "doxygen",
+                        "doxygen-notypes",
                         "google",
                         "google-notypes",
-                        "sphinx",
-                        "sphinx-notypes",
                         "numpy",
                         "numpy-notypes",
-                        "one-line-sphinx"
+                        "one-line-sphinx",
+                        "pep257",
+                        "sphinx",
+                        "sphinx-notypes"
                     ],
                     "description": "Which docstring format to use."
                 },

diff --git a/src/docstring/templates/doxygen-notypes.mustache b/src/docstring/templates/doxygen-notypes.mustache
@@ -0,0 +1,32 @@
+{{! Doxygen Docstring Template }}
+!
+@brief {{summaryPlaceholder}}
+
+{{extendedSummaryPlaceholder}}
+{{#parametersExist}}
+
+{{#args}}
+@param {{var}}: {{descriptionPlaceholder}}
+{{/args}}
+{{#kwargs}}
+@param {{var}}: {{descriptionPlaceholder}}. Defaults to {{&default}}.
+{{/kwargs}}
+{{/parametersExist}}
+{{#returnsExist}}
+
+{{#returns}}
+@return: {{descriptionPlaceholder}}
+{{/returns}}
+{{/returnsExist}}
+{{#exceptionsExist}}
+
+{{#exceptions}}
+@exception: {{descriptionPlaceholder}}
+{{/exceptions}}
+{{/exceptionsExist}}
+{{#yieldsExist}}
+
+{{#yields}}
+@returns: {{descriptionPlaceholder}}
+{{/yields}}
+{{/yieldsExist}}
diff --git a/src/docstring/templates/doxygen.mustache b/src/docstring/templates/doxygen.mustache
@@ -0,0 +1,32 @@
+{{! Doxygen Docstring Template }}
+!
+@brief {{summaryPlaceholder}}
+
+{{extendedSummaryPlaceholder}}
+{{#parametersExist}}
+
+{{#args}}
+@param {{var}} ({{typePlaceholder}}): {{descriptionPlaceholder}}
+{{/args}}
+{{#kwargs}}
+@param {{var}} ({{typePlaceholder}}, optional): {{descriptionPlaceholder}}. Defaults to {{&default}}.
+{{/kwargs}}
+{{/parametersExist}}
+{{#returnsExist}}
+
+{{#returns}}
+@return ({{typePlaceholder}}): {{descriptionPlaceholder}}
+{{/returns}}
+{{/returnsExist}}
+{{#exceptionsExist}}
+
+{{#exceptions}}
+@exception {{type}}: {{descriptionPlaceholder}}
+{{/exceptions}}
+{{/exceptionsExist}}
+{{#yieldsExist}}
+
+{{#yields}}
+@returns {{typePlaceholder}}: {{descriptionPlaceholder}}
+{{/yields}}
+{{/yieldsExist}}