AngularJS가있는 JSDoc

Question

현재 내 프로젝트에서 JSDoc을 사용하고 있으며 최근에 Angular를 구현하기 시작했으며 JSDoc을 계속 사용하여 모든 문서가 같은 위치에 있는지 확인하고자합니다.

저는 주로 ngDoc을 사용하는 사람들을 살펴 봤습니다. 그러나 우리는 항상 별도의 JavaScript를 사용하기 때문에 가능한 모든 옵션을 제공하지는 않습니다.

/** 
* @author Example <jon.doe@example.com> 
* @copyright 2014 Example Ltd. All rights reserved. 
*/ 
(function() { 
    window.example = window.example || {}; 
    /** 
    * Example Namespace 
    * @memberOf example 
    * @namespace example.angular 
    */ 
    window.example.angular = window.example.angular || {}; 
    var exAngular = window.example.angular; 

    /** 
    * A Example Angular Bootstrap Module 
    * @module exampleAngularBootstrap 
    */ 
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [ 
      'ngRoute', 
      'ngResource', 
      'ngCookies' 
     ]) 
     .run(function ($http, $cookies) { 
      $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken; 
      $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken; 
     }); 
})(); 

현재 이것은 내가 가지고있는 것이지만 run() 아이디어에 대한 문서를 넣을 수 없습니까?

Answer 1

등의 일에 그 함수를 호출의 경로를 아래로 가고 있었다. 지금과 같이 jsdoc 코멘트를 통해 AngularJS와 코드에 대한 문서를 작성 중 :

1.Make 빈의 .js는 다음과 같은 코멘트와 함께 파일 :

/** 
    * @namespace angular_module 
    */ 

이이 목록에 대한 생성 된 문서에 별도의 HTML을 생성합니다 모든 모듈. 새로운 각도 모듈을 정의

2.In 자바 스크립트 파일은

/** 
    * @class angular_module.MyModule 
    * @memberOf angular_module  
    */ 

이 모든 angular_modules의 위의 목록에 항목을 추가뿐만 아니라에 대한 별도의 HTML 페이지를 생성합니다 주석의이 종류를 사용 MyModule, 클래스이기 때문에.

/** 
    * @function myService 
    * @memberOf angular_module.MyModule 
    * @description This is an angularjs service. 
    */ 

이이 서비스에 대한 인 MyModule 페이지에서 항목을 추가합니다 :

3.For 각 AngularJS와 서비스는 다음 주석을 사용합니다. 이것은 함수로서 추가되었으므로, '@param'을 사용하여 입력 매개 변수에 대한 문서를 작성하고 '@return'을 사용하여 값을 리턴 할 수 있습니다.

4. 컨트롤러 또는 MyModule의 지시문에 꽤 긴 코드가 있고이를 문서화하기 위해 별도의 html 파일을 갖고 싶으면 전체 경로를 사용하여 컨트롤러 또는 지시문에 주석을 추가합니다. 예 :

/** 
    * @class angular_module.MyModule.MyController 
    */ 

이렇게하면 MyController가 MyModule의 설명서 페이지에 하나의 항목으로 나열됩니다.

그런 다음 컨트롤러 내의 코드에 MyController의 멤버 함수로 주석을 추가 할 수 있습니다.

/** 
    * @name $scope.aScopeFunction 
    * @function 
    * @memberOf angular_module.MyModule.MyController 
    * @description 
    */ 

이렇게하면이 함수의 문서가 MyController의 html 페이지의 html 파일에 나타납니다. 점으로 구분 된 전체 경로 문자열은 연결을 작성합니다. 구문의 세 가지 유형 namepath에 대한 있습니다

:

• 사람 번호라는 // 인스턴스 방법」이라고한다. "라고
• Person.say // "say"라는 정적 메서드.라고한다. "
• 사람 ~라는 내부 방법 // 말하는"새로운 "생성에 컨트롤러 이름 앞에 발견 될 것이다"

그러나, 클래스로 컨트롤러를 주석 한 불완전한 점은 있다는 것입니다 " html 문서는 클래스 생성자로 설명되어 있기 때문에

5. 또한 계층 구조를 추가하기 위해 네임 스페이스를 정의 할 수 있습니다. 예를 들어 모든 컨트롤러를 포함하도록 네임 스페이스를 정의 할 수 있습니다

   /** 
   * @namespace MyApp.Controllers 
   */ 
   

모든 컨트롤러의 접두어는 MyApp.Controllers입니다. 또한 등 MyApp.Product 또는 MyApp.Customer 같은 네임 스페이스를 정의 할 수 있습니다

비록 완벽하지, 내가 뭔가를 간단

1. 때문에 AngularJS와 코드를 문서화하는 jsdoc를 사용하여 좋아;
2. 모듈 컨트롤러 기능 계층 구조가 유지됩니다.
3. 그리고 jsdoc의 장점은 탐색 가능한 문서 사이트라는 것입니다.

테이블 스타일 jsdoc 스타일 시트 :

는 특히, 나는 자바 API 문서와 같은 테이블 스타일에 기본 jsdoc 스타일 시트를 적용했습니다. 그것은 더 분명 해 보인다. 윈도우에서

는,이 파일을 대체 : C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles 그것을이다이 파일 https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

와 함께.

Answer 2

나는 위의 유형의 외부 기능을 만드는 등 .RUN 또는 공장 나뿐만 아니라이 문제가 발생했을

/** 
* @author Example <jon.doe@example.com> 
* @copyright 2014 Example Ltd. All rights reserved. 
*/ 
(function() { 
    window.example = window.example || {}; 
    /** 
    * Example Namespace 
    * @memberOf example 
    * @namespace example.angular 
    */ 
    window.example.angular = window.example.angular || {}; 
    var exAngular = window.example.angular; 
    /** 
    * My example bootstrap run function 
    * @param {object} $http {@link http://docs.angularjs.org/api/ng.$http} 
    * @param {[type]} $cookies {@link http://docs.angularjs.org/api/ngCookies.$cookies} 
    */ 
    var runFunction = function ($http, $cookies) { 
     $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken; 
     $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken; 
    }; 

    /** 
    * A Example Angular Bootstrap Module 
    * @memberOf example.angular 
    * @namespace example.angular.bootstrap 
    * @function bootstrap 
    * @example 
    *  &lt;div ng-app="exampleAngularBootstrap"&gt; 
    *   &lt;div ng-view&gt;&lt;/div&gt; 
    *  &lt;/div&gt; 
    */ 
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [ 
      'ngRoute', 
      'ngResource', 
      'ngCookies' 
     ]) 
     .run(runFunction); 
})();