Enable user to use the plural form of @return

[smt]

My team prefers (and enforces) @returns, so here's a PR of my personal hack to enable a configurable variation of the @return tag output.

The @return tag remains the default unless the g:jsdoc_return_plural option is set to 1.

g:jsdoc_return_plural           *g:jsdoc_return_plural
        Use the `@returns` tag instead of `@return`.

        Default value is '0'

[ryanoasis]

Seems like a good idea, especially since they are synonyms: http://usejsdoc.org/tags-returns.html

[smt]

It's possible that other synonyms might have support added in the future as well, so with that in mind, the var could be refactored to g:jsdoc_return_synonym, etc.

[ryanoasis]

@smt That is a good point. Maybe this is a good place to use dictionaries to logically group them as well. E.g.

g:jsdoc_tag_synonyms = {
  \  'return': 'returns',
  \  'description': 'desc',
  " etc...
\}

To let the user define override defaults

For reference here is the full list that have synonyms (from http://usejsdoc.org):

@abstract (synonyms: @virtual)
This member must be implemented (or overridden) by the inheritor.

@augments (synonyms: @extends)
Indicate that a symbol inherits from, ands adds to, a parent symbol.

@class (synonyms: @constructor)
This function is intended to be called with the "new" keyword.

@constant (synonyms: @const)
Document an object as a constant.

@default (synonyms: @defaultvalue)
Document the default value.

@description (synonyms: @desc)
Describe a symbol.

@external (synonyms: @host)
Identifies an external class, namespace, or module.

@file (synonyms: @fileoverview, @overview)
Describe a file.

@fires (synonyms: @emits)
Describe the events this method may fire.

@function (synonyms: @func, @method)
Describe a function or method.

@member (synonyms: @var)
Document a member.

@param (synonyms: @arg, @argument)
Document the parameter to a function.

@property (synonyms: @prop)
Document a property of an object.

@returns (synonyms: @return)
Document the return value of a function.

@throws (synonyms: @exception)
Describe what errors could be thrown.

{@link} (synonyms: {@linkcode}, {@linkplain})
Link to another item in the documentation.

[heavenshell]

Sorry for late response.

g:jsdoc_tag_synonyms = {
\ 'return': 'returns',
\ 'description': 'desc',
" etc...
}

I like this idea.
Pull requests are very welcome 😄

[smt]

👍 I can give it a go sometime this week, if nobody else beats me to it.

I'm closing this PR, and will reference it in a new PR.

[heavenshell]

@smt thx. I'm looking forward to your PR 😄

[ryanoasis]

👍

[ryanoasis]

@smt Just curious if you still plan on doing this? 😄

[smt]

@ryanoasis I got started on it, but didn't get very far before life got in the way. If you are game, feel free to grab this 😁

[ryanoasis]

@smt Totally understand that! Maybe if I remember I will check in in another few weeks 😄

I wouldn't start on any work unless I checked with you (no need to duplicate effort 😃)