JavascriptのDocについて真剣に考えたらこうなった。

JavascriptのDocの書き方できれいでいい書き方はなかろうか？
と考えた結果こうなった。

結論

javascript

/**
 * description
 *
 * @param  <type>  argument (required) description
 * @param  <type>  argument (optional) description
 * ...
 * @return <type>
 */

もっと詳しく書くとこんな感じ

javascript

/**
 * yup description
 *
 * @param  <string> name    (required) refer object name
 * @param  <mixed>  options (required) option parameters
 * @param  <object> args    (optional) extra option parameters
 * @return <string>
 */
function yup(name, options, args) {
  // ...stuff...
}

説明

Airbnb JavaScript Style Guideを基本的に準じてJavascriptを書いてます。
(Airbnb JavaScript Style Guideではdocについては触れてませんが、commentの例題的な感じで出ています)

変えたポイントは (required)、 (optional)をつけたところです。
たとえばPHPでは引数にデフォルト値を持たせたいときにこんな風にかけます。

PHP

public function yup(name, options, args = array()) {
  // ...stuff...
}

しかし、javascriptではこうはかけないわけです。

javascript

function yup(name, options, args = {}) {
  // ...stuff...
}

引数が必須かそうじゃないかがパッと見でわかりません。
なので、Docに書いてすぐにわかるようにしました。

このくらいでいいんじゃないのかな？
あんまり情報ありすぎても見づらくなるだけだし