Add typed params and return type support

Author: heavenshell

README.md

@@ -51,3 +51,27 @@ and puts your jsdoc above it:
 ```viml
 nmap <silent> <C-l> ?function<cr>:noh<cr><Plug>(jsdoc)
 ```
+
+## TypeScript
+Since ver 0.10.0 jsdoc.vim support TypeScript.
+
+```typescript
+function foo(foo: string): string {
+  return 'foo'
+}
+```
+
+`:JsDoc` would generate following.
+
+```typescript
+/**
+ * foo
+ *
+ * @param {string} foo
+ * @returns {string}
+ */
+function foo(foo: string): string {
+  return 'foo'
+}
+```
+`param` and `returns` set `type` automatically.

autoload/jsdoc.vim

@@ -1,7 +1,7 @@
 " File: jsdoc.vim
 " Author: NAKAMURA, Hisashi <https://github.com/sunvisor>
 " Modifyed: Shinya Ohyanagi <[email protected]>
-" Version:  0.9.1
+" Version:  0.10.0
 " WebPage:  http://github.com/heavenshell/vim-jsdoc/
 " Description: Generate JSDoc to your JavaScript file.
 " License: BSD, see LICENSE for more details.
@@ -50,6 +50,10 @@ let g:jsdoc_tags = exists('g:jsdoc_tags')
 " Fill in any missing ones with defaults, keeping user overrides
 call extend(g:jsdoc_tags, s:jsdoc_default_tags, 'keep')
 
+" Add param types when `g:jsdoc_input_description=1` and has typed parameter,
+" such as TypeScript.
+let s:candidate_type = ''
+
 " Return data types for argument type auto completion :)
 function! jsdoc#listDataTypes(A, L, P) abort
   let l:types = [
@@ -71,6 +75,13 @@ function! jsdoc#listDataTypes(A, L, P) abort
       \ 'typedArray', 'TypedArray',
       \ 'weakmap', 'WeakMap',
       \ 'weakset', 'WeakSet']
+
+  if s:candidate_type != ''
+    " Ignore Builtin types. Already defined at `l:types`.
+    if index(l:types, s:candidate_type) == -1
+      call insert(l:types, s:candidate_type, 0)
+    endif
+  endif
   return join(l:types, "\n")
 endfunction
 
@@ -92,9 +103,46 @@ let s:regexs = {
       \   'class':                 '^.\{-}\s*class\s*\([a-zA-Z_$][a-zA-Z0-9_$]*\).*$',
       \   'shorthand':             '^.\{-}\s*\([a-zA-Z_$][a-zA-Z0-9_$]*\)\s*(\s*\([^)]*\)\s*).*$',
       \   'static':                '^.\{-}\s*static\s*\([a-zA-Z_$][a-zA-Z0-9_$]*\)\s*(\s*\([^)]*\)\s*).*$',
-      \   'arrow':                 '^.\{-}\s*\([a-zA-Z_$][a-zA-Z0-9_$]*\)\s*[:=]\s*(\s*\([^)]*\)\s*)\s*=>.*$'
+      \   'arrow':                 '^.\{-}\s*\([a-zA-Z_$][a-zA-Z0-9_$]*\)\s*[:=]\s*(\s*\([^)]*\)\s*)\s*=>.*$',
+      \   'return_type':           ')\(:\|:\s\|\s*:\s*\)\([a-zA-Z]\+\).*$',
+      \   'interface':             '^.\{-}\s*interface\s*\([a-zA-Z_$][a-zA-Z0-9_$]*\).*$',
+      \   'access':                '^\(public\|protected\|private\)',
+      \   'implements':            '^.\{-}\s*implements\s*\(\([^{]*\)\).*$',
+      \   'extends':               '^.\{-}\s*extends\s*\([^\s*]\)'
       \ }
 
+function! s:trim(value)
+  return substitute(a:value, '\s', '', '')
+endfunction
+
+" If someday Vim support lambda use lambda.
+function! s:parse_type(args)
+  let results = []
+  for arg in a:args
+    if arg =~# ':'
+      let args = split(arg, ':')
+      let val = args[0]
+      if val =~# s:regexs['access']
+        "let val = substitute(split(val, s:regexs['access'])[0], '\s', '', '')
+        let val = s:trim(split(val, s:regexs['access'])[0])
+      endif
+
+      "let type = substitute(args[1], '\s', '', '')
+      let type = s:trim(args[1])
+      " Split keywaord args.
+      if type =~# '='
+        "let type = substitute(split(type, '=')[0], '\s', '', '')
+        let type = s:trim(split(type, '=')[0])
+      endif
+      call add(results, {'val': val, 'type': type})
+    else
+      call add(results, {'val': arg, 'type': ''})
+    endif
+  endfor
+
+  return results
+endfunction
+
 function! s:build_description(argType, arg) abort
   let l:description = ''
   let l:override = 0
@@ -113,7 +161,7 @@ function! s:build_description(argType, arg) abort
 
   " Prompt for description
   if l:override == 0
-    let l:inputDescription = input('Argument "' . a:arg . '" description: ')
+    let l:inputDescription = input('Argument "' . a:arg['val'] . '" description: ')
     if l:inputDescription !=# ''
       let l:description = l:inputDescription
     endif
@@ -181,74 +229,121 @@ function! s:hookArgs(lines, space, arg, hook, argType, argDescription) abort
 
 endfunction
 
-function! jsdoc#insert() abort
-  let l:line = getline('.')
-  let l:indentCharSpace = ' '
-  let l:indentCharTab   = '	'
-  let l:autoexpandtab   = &l:expandtab
-
-  if l:autoexpandtab == 0 " noexpandtab
-    " tabs
-    let l:indent      = indent('.') / &l:tabstop
-    let l:indentChar  = l:indentCharTab
-  elseif l:autoexpandtab == 1 " expandtab
-    " spaces
-    let l:indent      = indent('.')
-    let l:indentChar  = l:indentCharSpace
-  endif
+function! s:determine_style(line)
+  let l:is_class     = 0
+  let l:is_function  = 0
+  let l:is_named     = 0
+  let l:is_static    = 0
+  let l:is_interface = 0
+  let l:regex        = 0
 
-  let l:space = repeat(l:indentChar, l:indent)
-
-  " Determine function defintion style
-  let l:is_class    = 0
-  let l:is_function = 0
-  let l:is_named    = 0
-  let l:is_static   = 0
-  if l:line =~ s:regexs['function_declaration']
+  if a:line =~ s:regexs['function_declaration']
     let l:is_function = 1
     let l:is_named    = 1
     let l:regex       = s:regexs['function_declaration']
-  elseif l:line =~ s:regexs['function_expression']
+  elseif a:line =~ s:regexs['function_expression']
     let l:is_function = 1
     let l:is_named    = 1
     let l:regex       = s:regexs['function_expression']
-  elseif l:line =~ s:regexs['anonymous_function']
+  elseif a:line =~ s:regexs['anonymous_function']
     let l:is_function = 1
     let l:regex       = s:regexs['anonymous_function']
-  elseif g:jsdoc_enable_es6 == 1 && l:line =~ s:regexs['static']
+  elseif g:jsdoc_enable_es6 == 1 && a:line =~ s:regexs['static']
     let l:is_function = 1
     let l:is_named    = 1
     let l:is_static   = 1
     let l:regex       = s:regexs['static']
-  elseif (g:jsdoc_allow_shorthand == 1 || g:jsdoc_enable_es6 == 1) && l:line =~ s:regexs['shorthand']
-    echomsg string('shorthand')
+  elseif (g:jsdoc_allow_shorthand == 1 || g:jsdoc_enable_es6 == 1) && a:line =~ s:regexs['shorthand']
     let l:is_function = 1
     let l:is_named    = 1
     let l:regex       = s:regexs['shorthand']
-  elseif g:jsdoc_enable_es6 == 1 && l:line =~ s:regexs['arrow']
+  elseif g:jsdoc_enable_es6 == 1 && a:line =~ s:regexs['arrow']
     let l:is_function = 1
     let l:is_named    = 1
     let l:regex       = s:regexs['arrow']
-  elseif g:jsdoc_enable_es6 == 1 &&  l:line =~ s:regexs['class_extend']
+  elseif g:jsdoc_enable_es6 == 1 &&  a:line =~ s:regexs['class_extend']
     let l:is_class    = 1
     let l:is_named    = 1
     let l:regex       = s:regexs['class_extend']
-  elseif g:jsdoc_enable_es6 == 1 &&  l:line =~ s:regexs['class']
+  elseif g:jsdoc_enable_es6 == 1 && a:line =~ s:regexs['class']
     let l:is_class    = 1
     let l:is_named    = 1
     let l:regex       = s:regexs['class']
+  elseif a:line =~ s:regexs['interface']
+    let l:is_interface = 1
+    let l:is_named     = 1
+    let l:regex        = s:regexs['interface']
+  endif
+
+  return {
+        \ 'is_class':     l:is_class,
+        \ 'is_function':  l:is_function,
+        \ 'is_named':     l:is_named,
+        \ 'is_static':    l:is_static,
+        \ 'is_interface': l:is_interface,
+        \ 'regex':        l:regex,
+        \ }
+endfunction
+
+" Extract return type such as TypeScript.
+function! s:extract_return_type(line)
+  let l:return_type = ''
+  if a:line =~ s:regexs['return_type']
+    let matched = matchstr(a:line, s:regexs['return_type'], 0)
+    if matched != ''
+      " FIXME:
+      " If signature has union tyoe, such as `function foo(): string | number {`
+      " Regex `\([a-zA-Z]\+\).*$` would extract like `number | string {`.
+      " So delete `{` if exists.
+      let l:return_type = matchstr(matched, '\([a-zA-Z]\+\).*$', 0)
+      let l:return_type = substitute(l:return_type, '\(\s*{\|{\)', '', 'g')
+    endif
   endif
 
+  return l:return_type
+endfunction
+
+function! jsdoc#insert() abort
+  let l:line = getline('.')
+  let l:indentCharSpace = ' '
+  let l:indentCharTab   = '	'
+  let l:autoexpandtab   = &l:expandtab
+
+  if l:autoexpandtab == 0 " noexpandtab
+    " tabs
+    let l:indent      = indent('.') / &l:tabstop
+    let l:indentChar  = l:indentCharTab
+  elseif l:autoexpandtab == 1 " expandtab
+    " spaces
+    let l:indent      = indent('.')
+    let l:indentChar  = l:indentCharSpace
+  endif
+
+  let l:space = repeat(l:indentChar, l:indent)
+
+  " Determine function defintion style
+  let l:style        = s:determine_style(l:line)
+  let l:is_class     = l:style['is_class']
+  let l:is_function  = l:style['is_function']
+  let l:is_named     = l:style['is_named']
+  let l:is_static    = l:style['is_static']
+  let l:is_interface = l:style['is_interface']
+  let l:regex        = l:style['regex']
+
   let l:lines = []
   let l:desc = g:jsdoc_input_description == 1 ? input('Description: ') : ''
   call add(l:lines, l:space . '/**')
   call add(l:lines, l:space . ' * ' . l:desc)
-  if !l:is_class
+  " Class and interface generate only typed name.
+  if !l:is_class && !l:is_interface
     call add(l:lines, l:space . ' *')
   endif
 
   let l:funcName = ''
-  if l:is_function || l:is_class
+  let l:parent_class = ''
+  let l:implements = ''
+  let l:return_type = ''
+  if l:is_function || l:is_class || l:is_interface
 
     " Parse function definition
     " @FIXME: Does not work if function is split over several lines...
@@ -266,13 +361,23 @@ function! jsdoc#insert() abort
       let l:argString = substitute(l:line, l:regex, '\1', 'g')
     endif
     let l:args = []
-    let l:parent_class = ''
     if l:is_class
-      let l:parent_class = substitute(l:argString, '\s', '', '')
+      "let l:parent_class = substitute(l:argString, '\s', '', '')
+      if l:argString =~ s:regexs['implements']
+        let implements = s:trim(substitute(l:argString, s:regexs['implements'], '\1', 'g'))
+      endif
+      let l:extends = substitute(l:argString, s:regexs['extends'], '\1', 'g')
+      let l:parent_class = matchstr(l:extends, '^\([a-zA-Z0-9-_$]*\)')
     else
       let l:args = split(l:argString, '\s*,\s*')
     endif
 
+    " Return type for typed language such as TypeScript.
+    let l:return_type = s:extract_return_type(l:line)
+
+    " Parse typed args. ex: TypeScript's argument.
+    let l:args = s:parse_type(l:args)
+
     if g:jsdoc_additional_descriptions == 1
       call add(l:lines, l:space . ' * @name ' . l:funcName)
       call add(l:lines, l:space . ' * @' . g:jsdoc_tags['function'])
@@ -298,39 +403,50 @@ function! jsdoc#insert() abort
 
     let l:hook = keys(g:jsdoc_custom_args_hook)
     for l:arg in l:args
+      let s:candidate_type = ''
       if g:jsdoc_enable_es6 == 1
         " Remove `(` or `)` from args.
-        let l:arg = substitute(l:arg, '\((\|)\)', '', '')
+        let l:arg['val'] = substitute(l:arg['val'], '\((\|)\)', '', '')
       endif
 
       if g:jsdoc_allow_input_prompt == 1
-        let l:argType = input('Argument "' . l:arg . '" type: ', '', 'custom,jsdoc#listDataTypes')
+        if l:arg['type'] != ''
+          let s:candidate_type = l:arg['type']
+        endif
+        let l:argType = input('Argument "' . l:arg['val'] . '" type: ', '', 'custom,jsdoc#listDataTypes')
+        redraw | echo ''
         let l:argDescription = s:build_description(l:argType, l:arg)
         if g:jsdoc_custom_args_hook == {}
           " Prepend separator to start of description only if it was provided
           if l:argDescription !=# ''
             let l:argDescription = g:jsdoc_param_description_separator . l:argDescription
           endif
-          call add(l:lines, l:space . ' * @' . g:jsdoc_tags['param'] . ' {' . l:argType . '} ' . l:arg . l:argDescription)
+          call add(l:lines, l:space . ' * @' . g:jsdoc_tags['param'] . ' {' . l:argType . '} ' . l:arg['val'] . l:argDescription)
         else
-          let l:lines = s:hookArgs(l:lines, l:space, l:arg, l:hook, l:argType, l:argDescription)
+          let l:lines = s:hookArgs(l:lines, l:space, l:arg['val'], l:hook, l:argType, l:argDescription)
         endif
       else
         " Hook args.
-        let l:lines = s:hookArgs(l:lines, l:space, l:arg, l:hook, '', '')
+        let l:lines = s:hookArgs(l:lines, l:space, l:arg['val'], l:hook, l:arg['type'], '')
       endif
     endfor
   endif
 
-  if l:is_class
-    " Class does not need return description.
+  if l:is_class || l:is_interface
+    " Class and inteface does not need return description.
     if l:parent_class != ''
       call add(l:lines, l:space . ' *')
-      call add(l:lines, l:space . ' * @extends ' . l:parent_class)
+      if l:implements != ''
+        call add(l:lines, l:space . ' * @implements ' . '{' . l:implements . '}')
+      endif
+
+      call add(l:lines, l:space . ' * @extends ' . '{' . l:parent_class . '}')
     endif
   elseif g:jsdoc_return == 1
     if g:jsdoc_allow_input_prompt == 1
+      let s:candidate_type = l:return_type
       let l:returnType = input('Return type (blank for no @' . g:jsdoc_tags['returns'] . '): ', '', 'custom,jsdoc#listDataTypes')
+      redraw | echo ''
       let l:returnDescription = ''
       if l:returnType !=# ''
         if g:jsdoc_return_description == 1
@@ -342,7 +458,11 @@ function! jsdoc#insert() abort
         call add(l:lines, l:space . ' * @' . g:jsdoc_tags['returns'] . ' {' . l:returnType . '}' . l:returnDescription)
       endif
     else
-      call add(l:lines, l:space . ' * @' . g:jsdoc_tags['returns'] . ' {undefined}')
+      let l:return_type = l:return_type == ''
+            \ ? ' {undefined}'
+            \ : printf(' {%s}', l:return_type)
+
+      cal add(l:lines, l:space . ' * @' . g:jsdoc_tags['returns'] . l:return_type)
     endif
   endif
   call add(l:lines, l:space . ' */')