diff --git a/CHANGELOG.md b/CHANGELOG.md index f38db15..7dc72b8 100644 --- 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 index f2f25fe..7ea7e27 100644 --- 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 new file mode 100644 index 0000000..d8cd9c5 --- /dev/null +++ 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 index 91d95e9..95b3cd6 100644 --- 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 new file mode 100644 index 0000000..98ebd4d --- /dev/null +++ b/src/docstring/templates/doxygen-notypes.mustache @@ -0,0 +1,24 @@ +{{! Doxygen Docstring Template }} +! +@brief {{summaryPlaceholder}} + +{{extendedSummaryPlaceholder}} + +{{#args}} +@param {{var}}: {{descriptionPlaceholder}} +{{/args}} +{{#kwargs}} +@param {{var}}: {{descriptionPlaceholder}}. Defaults to {{&default}}. +{{/kwargs}} + +{{#returns}} +@return {{descriptionPlaceholder}} +{{/returns}} + +{{#exceptions}} +@exception {{descriptionPlaceholder}} +{{/exceptions}} + +{{#yields}} +@returns {{descriptionPlaceholder}} +{{/yields}} diff --git a/src/docstring/templates/doxygen.mustache b/src/docstring/templates/doxygen.mustache new file mode 100644 index 0000000..1d4904a --- /dev/null +++ b/src/docstring/templates/doxygen.mustache @@ -0,0 +1,24 @@ +{{! Doxygen Docstring Template }} +! +@brief {{summaryPlaceholder}} + +{{extendedSummaryPlaceholder}} + +{{#args}} +@param {{var}} ({{typePlaceholder}}): {{descriptionPlaceholder}} +{{/args}} +{{#kwargs}} +@param {{var}} ({{typePlaceholder}}, optional): {{descriptionPlaceholder}}. Defaults to {{&default}}. +{{/kwargs}} + +{{#returns}} +@return ({{typePlaceholder}}): {{descriptionPlaceholder}} +{{/returns}} + +{{#exceptions}} +@exception {{type}}: {{descriptionPlaceholder}} +{{/exceptions}} + +{{#yields}} +@returns {{typePlaceholder}}: {{descriptionPlaceholder}} +{{/yields}}