feat(c,cpp): add docblock tag custom char config option (closes #534)

kkoomen · May 1, 2023 · f772669 · f772669
1 parent d0a2a2a
commit f772669
Show file tree

Hide file tree

Showing 5 changed files with 340 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -331,6 +331,16 @@ let g:doge_python_settings = {
 - `omit_redundant_param_types`: Whether or not to omit the `{type}` part of
   parameters and return types when the type is known.
 
+### Doxygen
+
+```vim
+let g:doge_doxygen_settings = {
+\  'char': '@'
+\}
+```
+
+- `char`: Character to use for docblock tags. Use `'@'` for `@param` or `'\'` for `\param`.
+
 # Headless mode
 
 If you're running your vim commands inside a docker, CI or similar environments

diff --git a/ftplugin/c.vim b/ftplugin/c.vim
@@ -14,6 +14,7 @@ endif
 
 let b:doge_parser = 'c'
 let b:doge_insert = 'above'
+let b:char = get(g:, 'doge_doxygen_settings')['char']
 
 let b:doge_supported_doc_standards = doge#buffer#get_supported_doc_standards([
       \ 'doxygen_javadoc',
@@ -41,7 +42,7 @@ let b:doge_patterns = doge#buffer#get_patterns()
 let s:function_pattern = {
 \  'nodeTypes': ['function_definition', 'declaration'],
 \  'parameters': {
-\    'format': '@param {name} !description',
+\    'format': b:char . 'param {name} !description',
 \  },
 \}
 
@@ -59,7 +60,7 @@ let s:field_pattern = {
 \  'nodeTypes': ['field_declaration'],
 \  'template': [
 \    '/**',
-\    ' * @{name} !description',
+\    ' * ' . b:char . '{name} !description',
 \    ' */',
 \  ],
 \}
@@ -74,10 +75,10 @@ call doge#buffer#register_doc_standard('doxygen_javadoc', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/**',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      ' *',
 \      '%(parameters| * {parameters})%',
-\      '%(returnType| * @return !description)%',
+\      '%(returnType| * ' . b:char . 'return !description)%',
 \      ' */',
 \    ],
 \  }),
@@ -95,10 +96,10 @@ call doge#buffer#register_doc_standard('doxygen_javadoc_no_asterisk', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/**',
-\      '@brief !summary',
+\      b:char . 'brief !summary',
 \      '',
 \      '%(parameters|{parameters})%',
-\      '%(returnType|@return !description)%',
+\      '%(returnType|' . b:char . 'return !description)%',
 \      '*/',
 \    ],
 \  }),
@@ -116,10 +117,10 @@ call doge#buffer#register_doc_standard('doxygen_javadoc_banner', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/*******************************************************************************',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      ' *',
 \      '%(parameters| * {parameters})%',
-\      '%(returnType| * @return !description)%',
+\      '%(returnType| * ' . b:char . 'return !description)%',
 \      ' ******************************************************************************/',
 \    ],
 \  }),
@@ -137,10 +138,10 @@ call doge#buffer#register_doc_standard('doxygen_qt', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/*!',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      ' *',
 \      '%(parameters| * {parameters})%',
-\      '%(returnType| * @return !description)%',
+\      '%(returnType| * ' . b:char . 'return !description)%',
 \      ' */',
 \    ],
 \  }),
@@ -158,10 +159,10 @@ call doge#buffer#register_doc_standard('doxygen_qt_no_asterisk', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/*!',
-\      '@brief !summary',
+\      b:char . 'brief !summary',
 \      '',
 \      '%(parameters|{parameters})%',
-\      '%(returnType|@return !description)%',
+\      '%(returnType|' . b:char . 'return !description)%',
 \      '*/',
 \    ],
 \  }),
@@ -203,10 +204,10 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_slash', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '///',
-\      '/// @brief !summary',
+\      '/// ' . b:char . 'brief !summary',
 \      '///',
 \      '%(parameters|/// {parameters})%',
-\      '%(returnType|/// @return !description)%',
+\      '%(returnType|/// ' . b:char . 'return !description)%',
 \      '///',
 \    ],
 \  }),
@@ -224,10 +225,10 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_exclamation', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '//!',
-\      '//! @brief !summary',
+\      '//! ' . b:char . 'brief !summary',
 \      '//!',
 \      '%(parameters|//! {parameters})%',
-\      '%(returnType|//! @return !description)%',
+\      '%(returnType|//! ' . b:char . 'return !description)%',
 \      '//!',
 \    ],
 \  }),
@@ -245,10 +246,10 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_slash_banner', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '////////////////////////////////////////////////////////////////////////////////',
-\      '/// @brief !summary',
+\      '/// ' . b:char . 'brief !summary',
 \      '///',
 \      '%(parameters|/// {parameters})%',
-\      '%(returnType|/// @return !description)%',
+\      '%(returnType|/// ' . b:char . 'return !description)%',
 \      '////////////////////////////////////////////////////////////////////////////////',
 \    ],
 \  }),

diff --git a/ftplugin/cpp.vim b/ftplugin/cpp.vim
@@ -8,6 +8,7 @@ set cpoptions&vim
 
 let b:doge_parser = 'cpp'
 let b:doge_insert = 'above'
+let b:char = get(g:, 'doge_doxygen_settings')['char']
 
 let b:doge_supported_doc_standards = doge#buffer#get_supported_doc_standards([
       \ 'doxygen_javadoc',
@@ -29,10 +30,10 @@ let b:doge_patterns = doge#buffer#get_patterns()
 " ==============================================================================
 let s:pattern_base = {
 \  'parameters': {
-\    'format': '@param {name} !description',
+\    'format': b:char . 'param {name} !description',
 \  },
 \  'typeParameters': {
-\    'format': '@tparam {name} !description',
+\    'format': b:char . 'tparam {name} !description',
 \  },
 \}
 
@@ -77,7 +78,7 @@ let s:field_pattern = doge#helpers#deepextend(s:pattern_base, {
 \  'nodeTypes': ['field_declaration'],
 \  'template': [
 \    '/**',
-\    ' * @{name} !description',
+\    ' * ' . b:char . '{name} !description',
 \    ' */',
 \  ],
 \})
@@ -94,7 +95,7 @@ call doge#buffer#register_doc_standard('doxygen_javadoc', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '/**',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      '%(typeParameters| *)%',
 \      '%(typeParameters| * {typeParameters})%',
 \      ' */',
@@ -103,11 +104,11 @@ call doge#buffer#register_doc_standard('doxygen_javadoc', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/**',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      ' *',
 \      '%(typeParameters| * {typeParameters})%',
 \      '%(parameters| * {parameters})%',
-\      '%(returnType| * @return !description)%',
+\      '%(returnType| * ' . b:char . 'return !description)%',
 \      ' */',
 \    ],
 \  }),
@@ -127,7 +128,7 @@ call doge#buffer#register_doc_standard('doxygen_javadoc_no_asterisk', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '/**',
-\      '@brief !summary',
+\      b:char . 'brief !summary',
 \      '%(typeParameters|)%',
 \      '%(typeParameters|{typeParameters})%',
 \      ' */',
@@ -136,11 +137,11 @@ call doge#buffer#register_doc_standard('doxygen_javadoc_no_asterisk', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/**',
-\      '@brief !summary',
+\      b:char . 'brief !summary',
 \      '',
 \      '%(typeParameters|{typeParameters})%',
 \      '%(parameters|{parameters})%',
-\      '%(returnType|@return !description)%',
+\      '%(returnType|' . b:char . 'return !description)%',
 \      '*/',
 \    ],
 \  }),
@@ -160,7 +161,7 @@ call doge#buffer#register_doc_standard('doxygen_javadoc_banner', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '/*******************************************************************************',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      '%(typeParameters| *)%',
 \      '%(typeParameters| * {typeParameters})%',
 \      ' ******************************************************************************/',
@@ -169,11 +170,11 @@ call doge#buffer#register_doc_standard('doxygen_javadoc_banner', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/*******************************************************************************',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      ' *',
 \      '%(typeParameters| * {typeParameters})%',
 \      '%(parameters| * {parameters})%',
-\      '%(returnType| * @return !description)%',
+\      '%(returnType| * ' . b:char . 'return !description)%',
 \      ' ******************************************************************************/',
 \    ],
 \  }),
@@ -193,7 +194,7 @@ call doge#buffer#register_doc_standard('doxygen_qt', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '/*!',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      '%(typeParameters| *)%',
 \      '%(typeParameters| * {typeParameters})%',
 \      ' */',
@@ -202,11 +203,11 @@ call doge#buffer#register_doc_standard('doxygen_qt', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/*!',
-\      ' * @brief !summary',
+\      ' * ' . b:char . 'brief !summary',
 \      ' *',
 \      '%(typeParameters| * {typeParameters})%',
 \      '%(parameters| * {parameters})%',
-\      '%(returnType| * @return !description)%',
+\      '%(returnType| * ' . b:char . 'return !description)%',
 \      ' */',
 \    ],
 \  }),
@@ -226,7 +227,7 @@ call doge#buffer#register_doc_standard('doxygen_qt_no_asterisk', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '/*!',
-\      '@brief !summary',
+\      b:char . 'brief !summary',
 \      '%(typeParameters|)%',
 \      '%(typeParameters|{typeParameters})%',
 \      ' */',
@@ -235,11 +236,11 @@ call doge#buffer#register_doc_standard('doxygen_qt_no_asterisk', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '/*!',
-\      '@brief !summary',
+\      b:char . 'brief !summary',
 \      '',
 \      '%(typeParameters|{typeParameters})%',
 \      '%(parameters|{parameters})%',
-\      '%(returnType|@return !description)%',
+\      '%(returnType|' . b:char . 'return !description)%',
 \      '*/',
 \    ],
 \  }),
@@ -259,7 +260,7 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_slash', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '///',
-\      '/// @brief !summary',
+\      '/// ' . b:char . 'brief !summary',
 \      '%(typeParameters|///)%',
 \      '%(typeParameters|/// {typeParameters})%',
 \      '///',
@@ -268,11 +269,11 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_slash', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '///',
-\      '/// @brief !summary',
+\      '/// ' . b:char . 'brief !summary',
 \      '///',
 \      '%(typeParameters|/// {typeParameters})%',
 \      '%(parameters|/// {parameters})%',
-\      '%(returnType|/// @return !description)%',
+\      '%(returnType|/// ' . b:char . 'return !description)%',
 \      '///',
 \    ],
 \  }),
@@ -292,7 +293,7 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_exclamation', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '//!',
-\      '//! @brief !summary',
+\      '//! ' . b:char . 'brief !summary',
 \      '%(typeParameters|//!)%',
 \      '%(typeParameters|//! {typeParameters})%',
 \      '//!',
@@ -301,11 +302,11 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_exclamation', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '//!',
-\      '//! @brief !summary',
+\      '//! ' . b:char . 'brief !summary',
 \      '//!',
 \      '%(typeParameters|//! {typeParameters})%',
 \      '%(parameters|//! {parameters})%',
-\      '%(returnType|//! @return !description)%',
+\      '%(returnType|//! ' . b:char . 'return !description)%',
 \      '//!',
 \    ],
 \  }),
@@ -325,7 +326,7 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_slash_banner', [
 \  doge#helpers#deepextend(s:class_pattern, {
 \    'template': [
 \      '////////////////////////////////////////////////////////////////////////////////',
-\      '/// @brief !summary',
+\      '/// ' . b:char . 'brief !summary',
 \      '%(typeParameters|///)%',
 \      '%(typeParameters|/// {typeParameters})%',
 \      '////////////////////////////////////////////////////////////////////////////////',
@@ -334,11 +335,11 @@ call doge#buffer#register_doc_standard('doxygen_cpp_comment_slash_banner', [
 \  doge#helpers#deepextend(s:function_pattern, {
 \    'template': [
 \      '////////////////////////////////////////////////////////////////////////////////',
-\      '/// @brief !summary',
+\      '/// ' . b:char . 'brief !summary',
 \      '///',
 \      '%(typeParameters|/// {typeParameters})%',
 \      '%(parameters|/// {parameters})%',
-\      '%(returnType|/// @return !description)%',
+\      '%(returnType|/// ' . b:char . 'return !description)%',
 \      '////////////////////////////////////////////////////////////////////////////////',
 \    ],
 \  }),

diff --git a/plugin/doge.vim b/plugin/doge.vim
@@ -163,6 +163,19 @@ if !exists('g:doge_comment_jump_modes')
   let g:doge_comment_jump_modes = ['n', 'i', 's']
 endif
 
+" Doxygen settings that will be used for all C-family languages.
+if !exists('g:doge_doxygen_settings')
+  let g:doge_doxygen_settings = {
+  \  'char': '@',
+  \}
+else
+  let s:doxygen_settings = get(g:, 'doge_doxygen_settings', {})
+  if has_key(s:doxygen_settings, 'char') && !(s:doxygen_settings['char'] ==# '@' || s:doxygen_settings['char'] ==# '\')
+    echoerr '[DoGe] "' . s:doxygen_settings['char'] . '" is not a valid character. Accepted characters are @ or \'
+  endif
+endif
+
+
 " Register all the <Plug> mappings.
 
 nnoremap <Plug>(doge-generate) :<C-u>call doge#generate(v:count)<CR>