[英]JSDoc with AngularJS
Currently within my Project we are using JSDoc, we have recently started to implement Angular and I want to continue using JSDoc to ensure that all the documentation is within the same place. 目前在我的项目中我们使用JSDoc,我们最近开始实现Angular,我想继续使用JSDoc来确保所有文档都在同一个地方。
I have taken a look at people mainly just saying to use ngDoc but this isn't really a viable option as we will always have separate JavaScript and I ideally would have everything together. 我看过人们主要只是说使用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;
});
})();
Currently this is what I have but am unable to put documentation for the run() any ideas? 目前这是我所拥有的但是无法为run()提供任何想法的文档?
I have encountered this issue as well. 我也遇到过这个问题。 I am now writing documentation for angularjs codes through jsdoc comments like this: 我现在通过像这样的jsdoc注释编写angularjs代码的文档:
1.Make a blank .js file with the following comment: 1.使用以下注释创建一个空白的.js文件:
/**
* @namespace angular_module
*/
This will create a separate html in the generated documentation for listing all modules. 这将在生成的文档中创建一个单独的html,用于列出所有模块。
2.In javascript files that defines any new angular module, use this kind of comment 2.在定义任何新角度模块的javascript文件中,使用此类注释
/**
* @class angular_module.MyModule
* @memberOf angular_module
*/
This will add an item in the above listing of all angular_modules, as well as creating a separate html page for MyModule, because it is a class. 这将在上面列出的所有angular_modules中添加一个项目,并为MyModule创建一个单独的html页面,因为它是一个类。
3.For each angularjs service, use the following comment: 3.对于每个angularjs服务,请使用以下注释:
/**
* @function myService
* @memberOf angular_module.MyModule
* @description This is an angularjs service.
*/
This will add an item in the MyModule page for the service. 这将在服务的MyModule页面中添加一个项目。 Because it is added as a function, you can write documentation for input parameters using '@param' and return values using '@return'. 因为它是作为函数添加的,所以您可以使用'@param'编写输入参数的文档,并使用'@return'返回值。
4.If I have quite long codes in a controller or directive of MyModule and want to have a separate html file to document it, I will annotate the controller or directive as a class using full path. 4.如果我在MyModule的控制器或指令中有很长的代码,并希望有一个单独的html文件来记录它,我将使用完整路径将控制器或指令注释为类。 eg 例如
/**
* @class angular_module.MyModule.MyController
*/
In this way, MyController will be listed as one item in MyModule's documentation page. 这样,MyController将在MyModule的文档页面中列为一个项目。
Then, we can annotate codes within the controller as member functions of MyController. 然后,我们可以在控制器中注释代码作为MyController的成员函数。
/**
* @name $scope.aScopeFunction
* @function
* @memberOf angular_module.MyModule.MyController
* @description
*/
In this way, this function's documentation will appear in the html file of MyController's html page. 这样,这个函数的文档将出现在MyController的html页面的html文件中。 The dot-separated full path string builds the connection. 以点分隔的完整路径字符串构建连接。
There are three types of syntaxes for namepath: namepath有三种类型的语法:
However, one imperfect point of commenting controller as a class is that a "new" will be found before the controller name in the generated html documentation because it is described as class constructor. 但是,将控制器注释为类的一个不完美之处在于,在生成的html文档中的控制器名称之前将找到“new”,因为它被描述为类构造函数。
Furthermore, you can define namespaces in order to add a hierarchical structure. 此外,您可以定义名称空间以添加分层结构。 For example, you can define a namespace to include all controllers 例如,您可以定义名称空间以包含所有控制器
/** * @namespace MyApp.Controllers */
, and prefix all controller with MyApp.Controllers
. ,并使用MyApp.Controllers
所有控制器添加MyApp.Controllers
。 You can also define namespaces like MyApp.Product
or MyApp.Customer
etc. 您还可以定义名称空间,如MyApp.Product
或MyApp.Customer
等。
Although not perfect, I like using jsdoc to document angularjs codes because 虽然不完美,但我喜欢使用jsdoc来记录angularjs代码,因为
A table style jsdoc stylesheet: 表格样式jsdoc样式表:
Particularly, I've adapted the default jsdoc stylesheet to a table style like the Java API documentation. 特别是,我已经将默认的jsdoc样式表改编为像Java API文档那样的表格样式。 It looks clearer. 它看起来更清晰。
In Windows, I replace this file: C:\\Users\\user1\\AppData\\Roaming\\npm\\node_modules\\jsdoc\\templates\\default\\static\\styles
with this file https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css 在Windows中,我替换此文件: C:\\Users\\user1\\AppData\\Roaming\\npm\\node_modules\\jsdoc\\templates\\default\\static\\styles
with this file https://github.com/gm2008/jsdoc/blob/master /templates/default/static/styles/jsdoc-default.css
That's it. 而已。
I have had to go down the route of creating the functions outside of the type above and calling those functions in such things as .run or factories etc. 我不得不沿着创建上述类型之外的函数的路线,并在诸如.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
* <div ng-app="exampleAngularBootstrap">
* <div ng-view></div>
* </div>
*/
exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
'ngRoute',
'ngResource',
'ngCookies'
])
.run(runFunction);
})();
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.