feat(#48): Support Shell

README.md

@@ -82,6 +82,7 @@ Is your favorite doc standard not supported?
 | :white_check_mark: | R                                              | [Roxygen2][roxygen2]                                                         |
 | :white_check_mark: | C++                                            | [Doxygen][doxygen]                                                           |
 | :white_check_mark: | C                                              | [Doxygen][doxygen], [KernelDoc][kerneldoc]                                   |
+| :white_check_mark: | Shell                                          | [Google][sh-google]                                                          |
 
 # Getting started
 
@@ -123,7 +124,7 @@ If you want to change the doc standard specifically for a buffer you can do:
 Here is the full list of available doc standards per filetype:
 
 | Variable                           | Default             | Supported                                                                                                                                    |
-| :--------------------------------- | :-----------        | :------------------------------------------------------------------------------------------------------------------------------------------- |
+| :--------------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------- |
 | `g:doge_doc_standard_python`       | `'reST'`            | `'reST'`, `'numpy'`, `'google'`, `'sphinx'`                                                                                                  |
 | `g:doge_doc_standard_php`          | `'phpdoc'`          | `'phpdoc'`                                                                                                                                   |
 | `g:doge_doc_standard_javascript`   | `'jsdoc'`           | `'jsdoc'`                                                                                                                                    |
@@ -138,6 +139,7 @@ Here is the full list of available doc standards per filetype:
 | `g:doge_doc_standard_r`            | `'roxygen2'`        | `'roxygen2'`                                                                                                                                 |
 | `g:doge_doc_standard_cpp`          | `'doxygen_javadoc'` | `'doxygen_javadoc'`, `'doxygen_javadoc_no_asterisk'`, `'doxygen_javadoc_banner'`, `'doxygen_qt'`, `'doxygen_qt_no_asterisk'`                 |
 | `g:doge_doc_standard_c`            | `'doxygen_javadoc'` | `'kernel_doc'`, `'doxygen_javadoc'`, `'doxygen_javadoc_no_asterisk'`, `'doxygen_javadoc_banner'`, `'doxygen_qt'`, `'doxygen_qt_no_asterisk'` |
+| `g:doge_doc_standard_sh`           | `'google'`          | `'google'`                                                                                                                                   |
 
 
 ## Options
@@ -310,6 +312,7 @@ DoGe is licensed under the GPL-3.0 license.
 [roxygen2]: https://github.com/klutometis/roxygen
 [doxygen]: http://www.doxygen.nl
 [kerneldoc]: https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
+[sh-style-guide]: https://google.github.io/styleguide/shell.xml#Function_Comments
 
 [demo-readme]: https://github.com/kkoomen/vim-doge/blob/master/doc/demos
 [suggest-language]: https://github.com/kkoomen/vim-doge/issues/new?labels=enhancement&template=feature_request.md&title=Add+support+for+<language>

autoload/doge/generate.vim

@@ -41,11 +41,11 @@ function! doge#generate#pattern(pattern) abort
           \ )
 
     " Extract the primary tokens.
-    let l:tokens = doge#token#extract(
+    let l:tokens = get(doge#token#extract(
           \ l:curr_line,
           \ a:pattern['match'],
           \ a:pattern['match_group_names']
-          \ )[0]
+          \ ), 0, {})
   endif
 
   try

autoload/doge/helpers.vim

@@ -62,7 +62,7 @@ endfunction
 " If no context is specified the todo-pattern is returned to search for.
 function! doge#helpers#placeholder(...) abort
   if !has_key(a:, 1)
-    return '\(\[TODO:[[:alnum:] ]\+\]\|TODO\)'
+    return '\(\[TODO:[[:alnum:]-]\+\]\|TODO\)'
   else
     return printf('[TODO:%s]', a:1)
   endif

autoload/doge/token.vim

@@ -79,7 +79,7 @@ function! s:token_replace(tokens, text) abort
   endfor
 
   " Replace !<name> with [TODO:<name>].
-  let l:text = substitute(l:text, '\m!\([[:alpha:]]\+\)', '[TODO:\1]', 'g')
+  let l:text = substitute(l:text, '\m!\([[:alpha:]-]\+\)', '[TODO:\1]', 'g')
 
   " Replace 2 or more white-spaces with 1 single white-space, except for leading
   " white-spaces and/or newlines. Those should be preserved.

ftplugin/sh.vim

@@ -0,0 +1,55 @@
+" ==============================================================================
+" The R documentation should follow the 'Roxygen2' conventions.
+" see https://github.com/klutometis/roxygen
+" ==============================================================================
+
+let s:save_cpo = &cpoptions
+set cpoptions&vim
+
+let b:doge_pattern_single_line_comment = '\m#.\{-}$'
+let b:doge_pattern_multi_line_comment = '\m#.\{-}$'
+
+let b:doge_supported_doc_standards = ['google']
+let b:doge_doc_standard = get(g:, 'doge_doc_standard_sh', b:doge_supported_doc_standards[0])
+if index(b:doge_supported_doc_standards, b:doge_doc_standard) < 0
+  echoerr printf(
+  \ '[DoGe] %s is not a valid Shell doc standard, available doc standard are: %s',
+  \ b:doge_doc_standard,
+  \ join(b:doge_supported_doc_standards, ', ')
+  \ )
+endif
+
+let b:doge_patterns = []
+
+" ==============================================================================
+" Matches regular functions.
+" ==============================================================================
+"
+" Matches the following scenarios:
+"
+"   function test {}
+"
+"   test() {}
+call add(b:doge_patterns, {
+\  'match': '\m^\(function\s\+[[:alnum:]_-]\+\|[[:alnum:]_-]\+\s*(.\{-})\)\s*{',
+\  'match_group_names': [],
+\  'comment': {
+\    'insert': 'above',
+\    'template': {
+\      'google': [
+\        '################################################################################',
+\        '# !description',
+\        '# Globals:',
+\        '# \t!var-name',
+\        '# Arguments:',
+\        '# \t$1: !description',
+\        '# Returns:',
+\        '# \t!description',
+\        '################################################################################',
+\      ],
+\    },
+\  },
+\})
+
+let &cpoptions = s:save_cpo
+unlet s:save_cpo

playground/test.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+################################################################################
+# [TODO:description]
+# Globals:
+#   [TODO:var-name]
+# Arguments:
+#   $1: [TODO:description]
+# Returns:
+#   [TODO:description]
+################################################################################
+function test {
+  print "foobar"
+}
+
+################################################################################
+# [TODO:description]
+# Globals:
+#   [TODO:var-name]
+# Arguments:
+#   $1: [TODO:description]
+# Returns:
+#   [TODO:description]
+################################################################################
+test() {
+  print "foobar"
+}

test/filetypes/sh/functions.vader

@@ -0,0 +1,43 @@
+# ==============================================================================
+# Regular functions.
+# ==============================================================================
+Given sh (regular functions):
+  function test {
+    print "foobar"
+  }
+
+  test() {
+    print "foobar"
+  }
+
+Do (trigger doge):
+  \<C-d>
+  :14\<CR>
+  \<C-d>
+
+Expect sh (generated comments with a descriptios and 'Globals', 'Arguments' and 'Returns' keywords):
+  ################################################################################
+  # [TODO:description]
+  # Globals:
+  #   [TODO:var-name]
+  # Arguments:
+  #   $1: [TODO:description]
+  # Returns:
+  #   [TODO:description]
+  ################################################################################
+  function test {
+    print "foobar"
+  }
+
+  ################################################################################
+  # [TODO:description]
+  # Globals:
+  #   [TODO:var-name]
+  # Arguments:
+  #   $1: [TODO:description]
+  # Returns:
+  #   [TODO:description]
+  ################################################################################
+  test() {
+    print "foobar"
+  }