Skip to content

Commit 1e40f53

Browse files
kkoomenkkoomen
authored
Merge pull request #640 from kkoomen/feature/python-doxygen
Implement doxygen doc standard for python
2 parents 6b7ce96 + e731259 commit 1e40f53

File tree

6 files changed

+169
-19
lines changed

6 files changed

+169
-19
lines changed

‎README.md

+19-19
Original file line numberDiff line numberDiff line change
@@ -74,24 +74,24 @@ Is your favorite language not supported?
7474
Is your favorite doc standard not supported?
7575
[Suggest a new doc standard][suggest-doc-standard] :tada:
7676

77-
| | Language | Doc standards |
78-
| :----------------- | :----------------------------------------------------- | :--------------------------------------------------------------------------- |
79-
| :white_check_mark: | Python | [reST][py-rest], [Numpy][py-numpy], [Google][py-google], [Sphinx][py-sphinx] |
80-
| :white_check_mark: | PHP | [phpdoc][phpdoc] |
81-
| :white_check_mark: | JavaScript (Vanilla, ES6, FlowJS, NodeJS, Svelte, Vue) | [JSDoc][jsdoc] |
82-
| :white_check_mark: | TypeScript | [JSDoc][jsdoc] |
83-
| :white_check_mark: | HTML (through inline `<script>` tags) | [JSDoc][jsdoc] |
84-
| :white_check_mark: | Lua | [LDoc][ldoc] |
85-
| :white_check_mark: | Java | [JavaDoc][javadoc] |
86-
| :white_check_mark: | Groovy | [JavaDoc][javadoc] |
87-
| :white_check_mark: | Ruby | [YARD][yard] |
88-
| :white_check_mark: | C++ | [Doxygen][doxygen] |
89-
| :white_check_mark: | C | [Doxygen][doxygen], [KernelDoc][kerneldoc] |
90-
| :white_check_mark: | C# | [XMLDoc][xmldoc] |
91-
| :white_check_mark: | Bash | [Google][sh-google] |
92-
| :white_check_mark: | Rust | [RustDoc][rustdoc] |
93-
| :white_check_mark: | R | [Roxygen2][roxygen2] |
94-
| :white_check_mark: | Scala | [ScalaDoc][scaladoc] |
77+
| | Language | Doc standards |
78+
| :----------------- | :----------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
79+
| :white_check_mark: | Python | [reST][py-rest], [Numpy][py-numpy], [Google][py-google], [Sphinx][py-sphinx], [Doxygen][doxygen] |
80+
| :white_check_mark: | PHP | [phpdoc][phpdoc] |
81+
| :white_check_mark: | JavaScript (Vanilla, ES6, FlowJS, NodeJS, Svelte, Vue) | [JSDoc][jsdoc] |
82+
| :white_check_mark: | TypeScript | [JSDoc][jsdoc] |
83+
| :white_check_mark: | HTML (through inline `<script>` tags) | [JSDoc][jsdoc] |
84+
| :white_check_mark: | Lua | [LDoc][ldoc] |
85+
| :white_check_mark: | Java | [JavaDoc][javadoc] |
86+
| :white_check_mark: | Groovy | [JavaDoc][javadoc] |
87+
| :white_check_mark: | Ruby | [YARD][yard] |
88+
| :white_check_mark: | C++ | [Doxygen][doxygen] |
89+
| :white_check_mark: | C | [Doxygen][doxygen], [KernelDoc][kerneldoc] |
90+
| :white_check_mark: | C# | [XMLDoc][xmldoc] |
91+
| :white_check_mark: | Bash | [Google][sh-google] |
92+
| :white_check_mark: | Rust | [RustDoc][rustdoc] |
93+
| :white_check_mark: | R | [Roxygen2][roxygen2] |
94+
| :white_check_mark: | Scala | [ScalaDoc][scaladoc] |
9595

9696
# Getting started
9797

@@ -162,7 +162,7 @@ Here is the full list of available doc standards per filetype:
162162

163163
| Variable | Default | Supported |
164164
| :------------------------------- | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
165-
| `g:doge_doc_standard_python` | `'reST'` | `'reST'`, `'numpy'`, `'google'`, `'sphinx'` |
165+
| `g:doge_doc_standard_python` | `'reST'` | `'reST'`, `'numpy'`, `'google'`, `'sphinx'`, `'doxygen'` |
166166
| `g:doge_doc_standard_php` | `'phpdoc'` | `'phpdoc'` |
167167
| `g:doge_doc_standard_javascript` | `'jsdoc'` | `'jsdoc'` |
168168
| `g:doge_doc_standard_html` | `'jsdoc'` | `'jsdoc'` |

‎doc/demos/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ Supported:
4949
- Doc standards
5050
- reST
5151
- Sphinx
52+
- Doxygen
5253
- Numpy
5354
- Google
5455
- Python 3.7+ type hints

‎ftplugin/python.vim

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ let b:doge_supported_doc_standards = [
1616
\ 'numpy',
1717
\ 'google',
1818
\ 'sphinx',
19+
\ 'doxygen',
1920
\ ]
2021
let b:doge_doc_standard = doge#buffer#get_doc_standard('python')
2122

‎helper/src/config.rs

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ pub fn load_doc_config_str<'a>(parser_name: &'a str, doc_name: &'a str) -> &'a s
55
"python_numpy" => include_str!("python/docs/numpy.yaml"),
66
"python_google" => include_str!("python/docs/google.yaml"),
77
"python_sphinx" => include_str!("python/docs/sphinx.yaml"),
8+
"python_doxygen" => include_str!("python/docs/doxygen.yaml"),
89

910
"cpp_doxygen_cpp_comment_exclamation" => include_str!("cpp/docs/doxygen_cpp_comment_exclamation.yaml"),
1011
"cpp_doxygen_cpp_comment_slash" => include_str!("cpp/docs/doxygen_cpp_comment_slash.yaml"),

‎helper/src/python/docs/doxygen.yaml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# https://www.woolseyworkshop.com/2020/06/25/documenting-python-programs-with-doxygen/
2+
3+
templates:
4+
function:
5+
node_types:
6+
- function_definition
7+
template: |
8+
{% if not params and not exceptions and not return_type %}
9+
"""! @brief [TODO:description]"""
10+
{% else %}
11+
"""!
12+
@brief [TODO:description]
13+
{% if params %}
14+
~
15+
{% for param in params %}
16+
@param {{ param.name }} [TODO:description]
17+
{% endfor %}
18+
{% endif %}
19+
{% if return_type %}
20+
~
21+
@return [TODO:description]
22+
{% endif %}
23+
{% if exceptions %}
24+
~
25+
{% for exception in exceptions %}
26+
@throws {{ exception.name | default(value="[TODO:name]") }} [TODO:description]
27+
{% endfor %}
28+
{% endif %}
29+
"""
30+
{% endif %}

‎test/filetypes/python/functions-doc-doxygen.vader

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# ==============================================================================
2+
# Functions using the Doxygen doc standard.
3+
# ==============================================================================
4+
Given python(function without parameters without return type where b:doge_doc_standard='doxygen'):
5+
def myFunc():
6+
pass
7+
8+
Do (trigger doge):
9+
:let b:doge_doc_standard='doxygen'\<CR>
10+
\<C-d>
11+
12+
Expect python (generated comment with nothing but the text 'TODO'):
13+
def myFunc():
14+
"""! @brief [TODO:description]"""
15+
pass
16+
17+
# ------------------------------------------------------------------------------
18+
19+
Given python(function with parameters without type hints without return type where b:doge_doc_standard='doxygen'):
20+
def myFunc(p1, p2, p3 = ''):
21+
pass
22+
23+
Do (trigger doge):
24+
:let b:doge_doc_standard='doxygen'\<CR>
25+
\<C-d>
26+
27+
Expect python (generated comment without type hints with defaults and optional):
28+
def myFunc(p1, p2, p3 = ''):
29+
"""!
30+
@brief [TODO:description]
31+
32+
@param p1 [TODO:description]
33+
@param p2 [TODO:description]
34+
@param p3 [TODO:description]
35+
"""
36+
pass
37+
38+
# ------------------------------------------------------------------------------
39+
40+
Given python(function with parameters with type hints without return type where b:doge_doc_standard='doxygen'):
41+
def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []):
42+
pass
43+
44+
Do (trigger doge):
45+
:let b:doge_doc_standard='doxygen'\<CR>
46+
\<C-d>
47+
48+
Expect python (generated comment with type hints, defaults and optional):
49+
def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []):
50+
"""!
51+
@brief [TODO:description]
52+
53+
@param p1 [TODO:description]
54+
@param p2 [TODO:description]
55+
@param p3 [TODO:description]
56+
"""
57+
pass
58+
59+
# ------------------------------------------------------------------------------
60+
61+
Given python(function with parameters with type hints with return type where b:doge_doc_standard='doxygen'):
62+
def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
63+
pass
64+
65+
Do (trigger doge):
66+
:let b:doge_doc_standard='doxygen'\<CR>
67+
\<C-d>
68+
69+
Expect python (generated comment with @param and @return tags):
70+
def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
71+
"""!
72+
@brief [TODO:description]
73+
74+
@param p1 [TODO:description]
75+
@param p2 [TODO:description]
76+
@param p3 [TODO:description]
77+
78+
@return [TODO:description]
79+
"""
80+
pass
81+
82+
# ==============================================================================
83+
# Read out the exceptions in the function body
84+
# ==============================================================================
85+
Given python (function with exceptions being raised in the body):
86+
def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
87+
try:
88+
foo = ValueError()
89+
raise foo
90+
raise Exception()
91+
except Exception as error:
92+
pass
93+
94+
Do (trigger doge):
95+
:let b:doge_doc_standard='doxygen'\<CR>
96+
\<C-d>
97+
98+
Expect python (generated comment with @param and @throws tags):
99+
def myFunc(p1, p2: Callable[[int], None], p3: Callable[[int, Exception], None] = []) -> Sequence[T]:
100+
"""!
101+
@brief [TODO:description]
102+
103+
@param p1 [TODO:description]
104+
@param p2 [TODO:description]
105+
@param p3 [TODO:description]
106+
107+
@return [TODO:description]
108+
109+
@throws [TODO:name] [TODO:description]
110+
@throws Exception [TODO:description]
111+
"""
112+
try:
113+
foo = ValueError()
114+
raise foo
115+
raise Exception()
116+
except Exception as error:
117+
pass

0 commit comments

Comments
 (0)