-
-
Notifications
You must be signed in to change notification settings - Fork 51
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(python): implement doxygen doc standard (#637)
- Loading branch information
Showing
6 changed files
with
169 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -49,6 +49,7 @@ Supported: | |
| - Doc standards | ||
| - reST | ||
| - Sphinx | ||
| - Doxygen | ||
| - Numpy | ||
| - Python 3.7+ type hints | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |