From e731259586d776f536fadbd24962515941df8252 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kim=20=E9=87=91=E5=8F=AF=E6=98=8E?= <koomen@protonmail.com>
Date: Fri, 27 Oct 2023 15:31:43 +0200
Subject: [PATCH] feat(python): implement doxygen doc standard (#637)

---
 README.md                                     |  38 +++---
 doc/demos/README.md                           |   1 +
 ftplugin/python.vim                           |   1 +
 helper/src/config.rs                          |   1 +
 helper/src/python/docs/doxygen.yaml           |  30 +++++
 .../python/functions-doc-doxygen.vader        | 117 ++++++++++++++++++
 6 files changed, 169 insertions(+), 19 deletions(-)
 create mode 100644 helper/src/python/docs/doxygen.yaml
 create mode 100644 test/filetypes/python/functions-doc-doxygen.vader

diff --git a/README.md b/README.md
index 286fb3b1..d8c548b6 100644
--- a/README.md
+++ b/README.md
@@ -74,24 +74,24 @@ Is your favorite language not supported?
 Is your favorite doc standard not supported?
 [Suggest a new doc standard][suggest-doc-standard] :tada:
 
-|                    | Language                                               | Doc standards                                                                |
-| :----------------- | :----------------------------------------------------- | :--------------------------------------------------------------------------- |
-| :white_check_mark: | Python                                                 | [reST][py-rest], [Numpy][py-numpy], [Google][py-google], [Sphinx][py-sphinx] |
-| :white_check_mark: | PHP                                                    | [phpdoc][phpdoc]                                                             |
-| :white_check_mark: | JavaScript (Vanilla, ES6, FlowJS, NodeJS, Svelte, Vue) | [JSDoc][jsdoc]                                                               |
-| :white_check_mark: | TypeScript                                             | [JSDoc][jsdoc]                                                               |
-| :white_check_mark: | HTML (through inline `<script>` tags)                  | [JSDoc][jsdoc]                                                               |
-| :white_check_mark: | Lua                                                    | [LDoc][ldoc]                                                                 |
-| :white_check_mark: | Java                                                   | [JavaDoc][javadoc]                                                           |
-| :white_check_mark: | Groovy                                                 | [JavaDoc][javadoc]                                                           |
-| :white_check_mark: | Ruby                                                   | [YARD][yard]                                                                 |
-| :white_check_mark: | C++                                                    | [Doxygen][doxygen]                                                           |
-| :white_check_mark: | C                                                      | [Doxygen][doxygen], [KernelDoc][kerneldoc]                                   |
-| :white_check_mark: | C#                                                     | [XMLDoc][xmldoc]                                                             |
-| :white_check_mark: | Bash                                                   | [Google][sh-google]                                                          |
-| :white_check_mark: | Rust                                                   | [RustDoc][rustdoc]                                                           |
-| :white_check_mark: | R                                                      | [Roxygen2][roxygen2]                                                         |
-| :white_check_mark: | Scala                                                  | [ScalaDoc][scaladoc]                                                         |
+|                    | Language                                               | Doc standards                                                                                    |
+| :----------------- | :----------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
+| :white_check_mark: | Python                                                 | [reST][py-rest], [Numpy][py-numpy], [Google][py-google], [Sphinx][py-sphinx], [Doxygen][doxygen] |
+| :white_check_mark: | PHP                                                    | [phpdoc][phpdoc]                                                                                 |
+| :white_check_mark: | JavaScript (Vanilla, ES6, FlowJS, NodeJS, Svelte, Vue) | [JSDoc][jsdoc]                                                                                   |
+| :white_check_mark: | TypeScript                                             | [JSDoc][jsdoc]                                                                                   |
+| :white_check_mark: | HTML (through inline `<script>` tags)                  | [JSDoc][jsdoc]                                                                                   |
+| :white_check_mark: | Lua                                                    | [LDoc][ldoc]                                                                                     |
+| :white_check_mark: | Java                                                   | [JavaDoc][javadoc]                                                                               |
+| :white_check_mark: | Groovy                                                 | [JavaDoc][javadoc]                                                                               |
+| :white_check_mark: | Ruby                                                   | [YARD][yard]                                                                                     |
+| :white_check_mark: | C++                                                    | [Doxygen][doxygen]                                                                               |
+| :white_check_mark: | C                                                      | [Doxygen][doxygen], [KernelDoc][kerneldoc]                                                       |
+| :white_check_mark: | C#                                                     | [XMLDoc][xmldoc]                                                                                 |
+| :white_check_mark: | Bash                                                   | [Google][sh-google]                                                                              |
+| :white_check_mark: | Rust                                                   | [RustDoc][rustdoc]                                                                               |
+| :white_check_mark: | R                                                      | [Roxygen2][roxygen2]                                                                             |
+| :white_check_mark: | Scala                                                  | [ScalaDoc][scaladoc]                                                                             |
 
 # Getting started
 
@@ -162,7 +162,7 @@ Here is the full list of available doc standards per filetype:
 
 | Variable                         | Default             | Supported                                                                                                                                                                                                                                              |
 | :------------------------------- | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `g:doge_doc_standard_python`     | `'reST'`            | `'reST'`, `'numpy'`, `'google'`, `'sphinx'`                                                                                                                                                                                                            |
+| `g:doge_doc_standard_python`     | `'reST'`            | `'reST'`, `'numpy'`, `'google'`, `'sphinx'`, `'doxygen'`                                                                                                                                                                                                            |
 | `g:doge_doc_standard_php`        | `'phpdoc'`          | `'phpdoc'`                                                                                                                                                                                                                                             |
 | `g:doge_doc_standard_javascript` | `'jsdoc'`           | `'jsdoc'`                                                                                                                                                                                                                                              |
 | `g:doge_doc_standard_html`       | `'jsdoc'`           | `'jsdoc'`                                                                                                                                                                                                                                              |
diff --git a/doc/demos/README.md b/doc/demos/README.md
index ffa338ec..ed76b8bc 100644
--- a/doc/demos/README.md
+++ b/doc/demos/README.md
@@ -49,6 +49,7 @@ Supported:
 - Doc standards
   - reST
   - Sphinx
+  - Doxygen
   - Numpy
   - Google
 - Python 3.7+ type hints
diff --git a/ftplugin/python.vim b/ftplugin/python.vim
index c74b0405..165d2d62 100644
--- a/ftplugin/python.vim
+++ b/ftplugin/python.vim
@@ -16,6 +16,7 @@ let b:doge_supported_doc_standards = [
       \ 'numpy',
       \ 'google',
       \ 'sphinx',
+      \ 'doxygen',
       \ ]
 let b:doge_doc_standard = doge#buffer#get_doc_standard('python')
 
diff --git a/helper/src/config.rs b/helper/src/config.rs
index f50eaf25..73bc6b80 100644
--- a/helper/src/config.rs
+++ b/helper/src/config.rs
@@ -5,6 +5,7 @@ pub fn load_doc_config_str<'a>(parser_name: &'a str, doc_name: &'a str) -> &'a s
         "python_numpy" => include_str!("python/docs/numpy.yaml"),
         "python_google" => include_str!("python/docs/google.yaml"),
         "python_sphinx" => include_str!("python/docs/sphinx.yaml"),
+        "python_doxygen" => include_str!("python/docs/doxygen.yaml"),
 
         "cpp_doxygen_cpp_comment_exclamation" => include_str!("cpp/docs/doxygen_cpp_comment_exclamation.yaml"),
         "cpp_doxygen_cpp_comment_slash" => include_str!("cpp/docs/doxygen_cpp_comment_slash.yaml"),
diff --git a/helper/src/python/docs/doxygen.yaml b/helper/src/python/docs/doxygen.yaml
new file mode 100644
index 00000000..3edd6b4f
--- /dev/null
+++ b/helper/src/python/docs/doxygen.yaml
@@ -0,0 +1,30 @@
+# https://www.woolseyworkshop.com/2020/06/25/documenting-python-programs-with-doxygen/
+
+templates:
+  function:
+    node_types:
+      - function_definition
+    template: |
+      {% if not params and not exceptions and not return_type %}
+      """! @brief [TODO:description]"""
+      {% else %}
+      """!
+      @brief [TODO:description]
+      {% if params %}
+      ~
+        {% for param in params %}
+      @param {{ param.name }} [TODO:description]
+        {% endfor %}
+      {% endif %}
+      {% if return_type %}
+      ~
+      @return [TODO:description]
+      {% endif %}
+      {% if exceptions %}
+      ~
+        {% for exception in exceptions %}
+      @throws {{ exception.name | default(value="[TODO:name]") }} [TODO:description]
+        {% endfor %}
+      {% endif %}
+      """
+      {% endif %}
diff --git a/test/filetypes/python/functions-doc-doxygen.vader b/test/filetypes/python/functions-doc-doxygen.vader
new file mode 100644
index 00000000..68b35816
--- /dev/null
+++ b/test/filetypes/python/functions-doc-doxygen.vader
@@ -0,0 +1,117 @@
+# ==============================================================================
+# Functions using the Doxygen doc standard.
+# ==============================================================================
+Given python(function without parameters without return type where b:doge_doc_standard='doxygen'):
+  def myFunc():
+    pass
+
+Do (trigger doge):
+  :let b:doge_doc_standard='doxygen'\<CR>
+  \<C-d>
+
+Expect python (generated comment with nothing but the text 'TODO'):
+  def myFunc():
+    """! @brief [TODO:description]"""
+    pass
+
+# ------------------------------------------------------------------------------
+
+Given python(function with parameters without type hints without return type where b:doge_doc_standard='doxygen'):
+  def myFunc(p1, p2, p3 = ''):
+    pass
+
+Do (trigger doge):
+  :let b:doge_doc_standard='doxygen'\<CR>
+  \<C-d>
+
+Expect python (generated comment without type hints with defaults and optional):
+  def myFunc(p1, p2, p3 = ''):
+    """!
+    @brief [TODO:description]
+
+    @param p1 [TODO:description]
+    @param p2 [TODO:description]
+    @param p3 [TODO:description]
+    """
+    pass
+
+# ------------------------------------------------------------------------------
+
+Given python(function with parameters with type hints without return type where b:doge_doc_standard='doxygen'):
+  def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []):
+    pass
+
+Do (trigger doge):
+  :let b:doge_doc_standard='doxygen'\<CR>
+  \<C-d>
+
+Expect python (generated comment with type hints, defaults and optional):
+  def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []):
+    """!
+    @brief [TODO:description]
+
+    @param p1 [TODO:description]
+    @param p2 [TODO:description]
+    @param p3 [TODO:description]
+    """
+    pass
+
+# ------------------------------------------------------------------------------
+
+Given python(function with parameters with type hints with return type where b:doge_doc_standard='doxygen'):
+  def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
+    pass
+
+Do (trigger doge):
+  :let b:doge_doc_standard='doxygen'\<CR>
+  \<C-d>
+
+Expect python (generated comment with @param and @return tags):
+  def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
+    """!
+    @brief [TODO:description]
+
+    @param p1 [TODO:description]
+    @param p2 [TODO:description]
+    @param p3 [TODO:description]
+
+    @return [TODO:description]
+    """
+    pass
+
+# ==============================================================================
+# Read out the exceptions in the function body
+# ==============================================================================
+Given python (function with exceptions being raised in the body):
+  def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
+    try:
+      foo = ValueError()
+      raise foo
+      raise Exception()
+    except Exception as error:
+      pass
+
+Do (trigger doge):
+  :let b:doge_doc_standard='doxygen'\<CR>
+  \<C-d>
+
+Expect python (generated comment with @param and @throws tags):
+  def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
+    """!
+    @brief [TODO:description]
+
+    @param p1 [TODO:description]
+    @param p2 [TODO:description]
+    @param p3 [TODO:description]
+
+    @return [TODO:description]
+
+    @throws [TODO:name] [TODO:description]
+    @throws Exception [TODO:description]
+    """
+    try:
+      foo = ValueError()
+      raise foo
+      raise Exception()
+    except Exception as error:
+      pass