From 35822474beca8e73597ea0477f1bddb56fc7a684 Mon Sep 17 00:00:00 2001
From: David O'Trakoun <me@davidosomething.com>
Date: Thu, 21 Jan 2016 23:37:16 -0500
Subject: [PATCH] add full regex mode for jsdoc_custom_args_hook (squashed with
 upstream)

---
 README.md          |  1 +
 autoload/jsdoc.vim | 21 ++++++++++++++++++++-
 doc/jsdoc.txt      | 45 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 072e98f..b8e3778 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@ Option                                  | Default | Description
 **g:jsdoc_allow_shorthand**             | 0       | Set value to 1 to allow ECMAScript6 shorthand syntax. Since ver `0.5.0` deprecated. Use `g:jsdoc_enable_es6` instead.
 **g:jsdoc_param_description_separator** | ' '     | Characters used to separate `@param` name and description.
 **g:jsdoc_custom_args_hook**            | {}      | Override default type and description. See help more detail.
+**g:jsdoc_custom_args_regex_only**      | 0       | When using `custom_args_hook`, only match against regexes
 **g:jsdoc_type_hook**                   | {}      | Allow to insert default description depending on the type.
 **g:jsdoc_enable_es6**                  | 0       | Enable to use ECMAScript6's Shorthand function, Arrow function.
 **g:jsdoc_tags**                        | see :h  | Allow use of alternate tags (the ones that support synonyms) per JSDoc documentation. Can be changed on a per tag basis, for example: `let g:jsdoc_tags = {} | let g:jsdoc_tags['param'] = 'arg'`
diff --git a/autoload/jsdoc.vim b/autoload/jsdoc.vim
index 86bafea..ead28fa 100644
--- a/autoload/jsdoc.vim
+++ b/autoload/jsdoc.vim
@@ -100,6 +100,10 @@ if !exists('g:jsdoc_enable_es6')
   let g:jsdoc_enable_es6 = 0
 endif
 
+if !exists('g:jsdoc_custom_args_regex_only')
+  let g:jsdoc_custom_args_regex_only = 0
+endif
+
 if g:jsdoc_allow_shorthand == 1
   echohl Error | echomsg 'g:jsdoc_allow_shorthand is deprecated. Use g:jsdoc_enable_es6 instead.' | echohl None
 endif
@@ -146,7 +150,22 @@ function! s:hookArgs(lines, space, arg, hook, argType, argDescription)
   if g:jsdoc_custom_args_hook == {}
     call add(a:lines, a:space . ' * @' . g:jsdoc_tags['param'] . ' ' . a:arg)
   else
-    let l:matchedArg = matchstr(a:hook, a:arg)
+
+    let l:matchedArg = ''
+
+    if g:jsdoc_custom_args_regex_only == 1
+      " Loop through regexes list `hook = keys(g:jsdoc_custom_args_hook)` to
+      " find first instance where the arg name is matched by the hook regex
+      for l:pat in a:hook
+        if !empty(matchstr(a:arg, l:pat))
+          let l:matchedArg = l:pat
+          break
+        endif
+      endfor
+    else
+      let l:matchedArg = matchstr(a:hook, a:arg)
+    endif
+
     if l:matchedArg == ''
       let l:type = '{' . a:argType . '} '
       let l:description = ''
diff --git a/doc/jsdoc.txt b/doc/jsdoc.txt
index e1fd73e..bac5112 100644
--- a/doc/jsdoc.txt
+++ b/doc/jsdoc.txt
@@ -168,6 +168,51 @@ g:jsdoc_custom_args_hook		*g:jsdoc_custom_args_hook*
 		function foo(bar, callback, cb) {
 		}
 
+g:jsdoc_custom_args_regex_only		*g:jsdoc_custom_args_regex_only*
+
+		Match against regexes only when using custom args.
+
+		Default value is 0
+
+		If you use this, you'll have to modify your custom arg keys
+		to be regexes. E.g.
+
+		let g:jsdoc_custom_args_regex_only = 1
+		let g:jsdoc_custom_args_hook = {
+			\   '^\$': {
+			\     'type': '{jQuery}'
+			\   },
+			\   'callback': {
+			\     'type': '{Function}',
+			\     'description': 'Callback function'
+			\   },
+			\   'data': {
+			\     'type': '{Object}'
+			\   },
+			\   '^e$': {
+			\     'type': '{Event}'
+			\   },
+			\   'el$': {
+			\     'type': '{Element}'
+			\   },
+			\   '\(err\|error\)$': {
+			\     'type': '{Error}'
+			\   },
+			\   'handler$': {
+			\     'type': '{Function}'
+			\   },
+			\   '^i$': {
+			\     'type': '{Number}'
+			\   },
+			\   '^_\?is': {
+			\     'type': '{Boolean}'
+			\   },
+			\   'options$': {
+			\     'type': '{Object}'
+			\   },
+			\ }
+
+
 g:jsdoc_type_hook					*g:jsdoc_type_hook*
 		Allow to insert default description depending on the type.