AngularJSプロジェクトにおけるngdoc・jsdocルール案

[HAKASHUN]

ポイント

1. 必ず書かないと行けないことを定義する
   • angular/materialが、丁寧すぎず、アノテーションもしっかりと書いているので、最も参考することとなった。
2. どうやって書くかを確認する
   • AngularJS公式ngdoc説明
   • JsDoc3-manual-jp
   • jsdoc TagReference
   • Google JavaScript スタイルガイド - 日本語訳
3. どうすれば楽に書けるかを考える

文献

• https://code.google.com/p/jsdoc-toolkit/wiki/TagReference

[HAKASHUN]

必ずなルール

/** ... */で囲まなければならない

• ngdoc・jsdocは/** ... */で囲まれた部分になる。
• エディタ側で意識することなくできるように対応しておくとよい。

記法スタイルを統一しなければならない

基本

/**
 * ここに名前
 * @param {number} [num] 数字。
 * @return {string} 文字列。
 */
function hoge(num) { ...

• 特に理由がなければ、上記のスタイルで各行の先頭に*があるコメントの仕方に統一し、コードの統一性と可視性を高める
• @example使用箇所は、その性質上、*が先頭にあってはならないので注意

AngularJS本体とあわせる

• 以下はAngularJSの$window Serviceの例
• 迷ったらAngularJSの本体コードを見て、どこまでどのようなことを書くべきかを確認する

/**
 * @ngdoc service
 * @name $window
 *
 * @description
 * A reference to the browser's `window` object. While `window`
 * is globally available in JavaScript, it causes testability problems, because
 * it is a global variable. In angular we always refer to it through the
 * `$window` service, so it may be overridden, removed or mocked for testing.
 *
 * Expressions, like the one defined for the `ngClick` directive in the example
 * below, are evaluated with respect to the current scope.  Therefore, there is
 * no risk of inadvertently coding in a dependency on a global value in such an
 * expression.
 *
 * @example
   <example module="windowExample">
     <file name="index.html">
       <script>
         angular.module('windowExample', [])
           .controller('ExampleController', ['$scope', '$window', function($scope, $window) {
             $scope.greeting = 'Hello, World!';
             $scope.doGreeting = function(greeting) {
               $window.alert(greeting);
             };
           }]);
       </script>
       <div ng-controller="ExampleController">
         <input type="text" ng-model="greeting" />
         <button ng-click="doGreeting(greeting)">ALERT</button>
       </div>
     </file>
     <file name="protractor.js" type="protractor">
      it('should display the greeting in the input box', function() {
       element(by.model('greeting')).sendKeys('Hello, E2E Tests');
       // If we click the button it will block the test runner
       // element(':button').click();
      });
     </file>
   </example>
 */

参考文献

• https://sites.google.com/site/jsdoc3manualjp/annotation

[HAKASHUN]

@ngdoc

AngularJSのソースでは以下が使われています。

• @ngdoc module (Ex. ngTouch)
• @ngdoc provider(Ex. $routeProvider)
• @ngdoc service
• @ngdoc directive
• @ngdoc filter
• @ngdoc method
• @ngdoc type
• @ngdoc property
• @ngdoc event
• @ngdoc function
• @ngdoc object
• @ngdoc input

Angular Materialのソースでは以下が使われています。

• @ngdoc module
• @ngdoc directive
• @ngdoc service
• @ngdoc object

Angular MaterialではAngular本体と比べて、docを書きすぎないようにしているのか、アノテーションの範囲が少ない感じでした。

• @ngdoc module
• @ngdoc directive
• @ngdoc service
• @ngdoc provider
• @ngdoc filter
• @ngdoc object

上記6つに絞ったルールでよいかもしれません。

[HAKASHUN]

@name

with @ngdoc module

• angular.module('{{モジュール名}}')の{{モジュール名}}をそのまま書く

/**
 * @ngdoc module
 * @name material.services.theming

 ...

angular.module('material.services.theming', []);

with @ngdoc directive

• Module.directive('{{ディレクティブ名}}')の{{ディレクティブ名}}をそのまま書く

/**
 * @ngdoc directive
 * @name mdSubheader

...

Module.directive('mdSubheader', [])

with @ngdoc service

• Module.factory('{{ファクトリ名}}')の{{ファクトリ名}}をそのまま書く
• Module.service('{{サービス名}}')の{{サービス名}}をそのまま書く

/**
 * @ngdoc service
 * @name $mdToast

...

Module.factory('$mdToast', [])

with @ngdoc provider

• Module.provider('{{プロバイダ名}}')の{{プロバイダ名}}をそのまま書く

/**
 * @ngdoc provider
 * @name $controllerProvider

...

Module.provider('$controllerProvider', [])

with @ngdoc filter

• Module.filter('{{フィルタ名}}')の{{フィルタ名}}をそのまま書く

/**
 * @ngdoc filter
 * @name orderBy

...

Module.filter('orderBy', [])

Ex. orderBy.js

with @ngdoc object

constant

• Module.constant('{{コンスタント名}}', {})の{{コンスタント名}}をそのまま書く

/**
 * @ngdoc object
 * @name $ionicLoadingConfig

...

Module.constant('$ionicLoadingConfig', {
  template: '<i class="icon ion-loading-d"></i>'
});

config

• Module.config([])の{{モジュール名}}.configをそのまま書く

/**
 * @ngdoc object
 * @name sample.config

...

angular.module('sample').config([function(){}]);

controller

• Docualrで独自に@ngdoc controllerを定義しているが、その他のngdoc的にはそのような定義は存在しない
• stackoverflowや、Angular Materialの例を見ると、controllerに対しては、@ngdoc objectを指定してあげる例が多いので採用する
• Module.controller('{{コントローラ名}}', [])の{{コントローラ名}}をそのまま書く

/**
 * @ngdoc object
 * @name mdSidenavController

...

function mdSidenavController($scope, $element...

Module.controller('mdSidenavController', mdSidenavController);

Ex. sidenav.js

[HAKASHUN]

@description

used to provide a description of a component in markdown
Writing-AngularJS-Documentation

jsDocでは、htmlを用いてdescriptionを書くこともありますが、AngularJSプロジェクトでは、Markdownによって記載することが多いです。

/**

...

 * @description
 * The `<md-card>` directive is a container element used within `<md-content>` containers.
 *
 * Cards have constant width and variable heights; where the maximum height is limited to what can
 * fit within a single view on a platform, but it can temporarily expand as needed

...

 */

[HAKASHUN]

@module

• ターゲットがどのモジュールに属しているかを明記します。
• @nameにモジュール名とターゲット名を含めるケースもありますが、モジュール名とターゲット固有の名前は分けて記述する方がわかりやすいと思います。
• @ngdoc moduleを記述している場合は、@nameと同じ内容を記述することになるため、省略します。

/**
 * @ngdoc module
 * @name material.components.sidenav
 *
 * @description
 * A Sidenav QP component.
 */
var Module = angular.module('material.components.sidenav', []);

/*
 * @ngdoc object
 * @name mdSidenavController
 * @module material.components.sidenav
 *
 * @description
 * The controller for mdSidenav components.
 */

...

Module.controller('mdSidenavController', mdSidenavController)

[HAKASHUN]

@param

基本の型

@param {type} name description

• type : 型情報
• name: 受け取る引数の名前
• description: 引数の説明文

typeのパターン

• 型情報は、ものによって定義の仕方が様々なので、今回は3パターンで見てみます。
• ※下記は厳密に調べていません><

AngularJS	Angular Material	ionic
string	string	string
boolean	boolean	boolean
Function	function	function / Function
number	number	number
Object	object	object/Object
DOMElement /Element	el	HTMLElement
expression	expression	expression
Error	使用箇所なし	使用箇所なし
RegExp	使用箇所なし	使用箇所なし
Array	使用箇所なし	使用箇所なし
		DOMEvent
		int
Promise/promise

typeの表現を以下に決めてみた

type
string
boolean
Function
number
Object
DOMElement
expression
Error
RegExp
Array
Promise

色々探したところだとこれが一番まとまっているかも?

http://www38.atwiki.jp/aias-jsstyleguide2/pages/17.html#id_6f37ee9a

その他のTips

複数の型を指定したいとき

• |でtypeをつなぐ

@param {string|DOMElement}

絶対にnullでない値であることを指定したいとき

• !をtypeの先頭に書く

@param {!Object}

省略可能な値(undefinedを許す)であることを指定したいとき

• =をtypeの後方に書く

@param {Object=}

nullとundefinedを意識した型定義

/** 
 * 4つの引数を取ります。そのうち2つはnullを許容し、2つは省略可能です。 
 * @param {!Object} nonNull 必須（undefinedは不可）、nullは不可。 
 * @param {Object} mayBeNull 必須（undefinedは不可）、nullでもよい。 
 * @param {!Object=} opt_nonNull 省略可 (undefinedでもよい)、しかし値があるなら、 
 *     それはnullであってはならない! 
 * @param {Object=} opt_mayBeNull 省略可 (undefinedでもよい)、nullでもよい。 
 */
function strangeButTrue(nonNull, mayBeNull, opt_nonNull, opt_mayBeNull) { 
 // ... 
};

[HAKASHUN]

@returns

基本の型

@returns {type} description

• typeとして使うものは、@paramで決めたものと同じ

Tips

どの型が返るかわからないとき

@returns {*}

[HAKASHUN]

@restrict(@ngdoc directive時のみ)

• 対象となるディレクティブのrestrictを指定する

@restrict E

[HAKASHUN]

ルールまとめ

• アノテーションするときに意識するものを絞る(ここでは7つ)
• それ以外もすぐに書けるのなら書いた方がよい
• 時間的コストを意識するのであれば、7つ以外は必須でない

アノテーションで必ず意識するべきアノテーション7選

1. @ngdoc
2. @name
3. @module
4. @description
5. @restrict
6. @param
7. @returns

@ngdoc タイプ別のアノテーション

• ○: 絶対書く
• ×: 書かない
• △: 時と場合で書くかも？

@ngdoc	@name	@module	@description	@restrict	@param	@returns
module	○	×	○	×	×	×
directive	○	○	○	○	△	×
service	○	○	○	×	△	○
provider	○	○	○	×	×	△
filter	○	○	○	×	○	○
object	○	○	○	×	×	×

これ以外のアノテーション

• 書かなくても良い
• 書いてあった方がもちろん良い