JSDoc与AngularJS [英] JSDoc with AngularJS
问题描述
目前我们使用JSDoc我的计划之内,我们最近开始实施角度,我想继续使用JSDoc,以确保所有的文件是在同一个地方之内。
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.
我已经采取了看的人主要只是说使用ngDoc但这不是真的如我们将始终有独立的JavaScript和我理想是拥有一切在一起一个可行的选择。
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.
/**
* @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()的任何想法?
Currently this is what I have but am unable to put documentation for the run() any ideas?
感谢您先进的!
推荐答案
我也遇到过这个问题为好。
I have encountered this issue as well. I am now writing documentation for angularjs codes through jsdoc comments like this:
词根记忆空白.js文件具有以下注释文件:
1.Make a blank .js file with the following comment:
/**
* @namespace angular_module
*/
这将创建生成的文档在一个单独的HTML上市的所有模块。
This will create a separate html in the generated documentation for listing all modules.
2.In定义任何新的角度模块的JavaScript文件,使用这种注释
2.In javascript files that defines any new angular module, use this kind of comment
/**
* @class angular_module.MyModule
* @memberOf angular_module
*/
这将在所有angular_modules上述上市添加项目,以及创建MyModule的一个单独的html页面,因为这是一类。
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.
3.对于每个angularjs服务,请使用以下注释:
3.For each angularjs service, use the following comment:
/**
* @function myService
* @memberOf angular_module.MyModule
* @description This is an angularjs service.
*/
这将在MyModule的页面中添加一个项目的服务。因为它是作为附加功能,您可以使用@param为输入参数编写文档,并使用'返回:'返回值。
This will add an item in the MyModule page for the service. Because it is added as a function, you can write documentation for input parameters using '@param' and return values using '@return'.
4.Furthermore,如果我在MyModule中的控制器或指令有相当长的codeS,并希望有一个独立的HTML文件来记录它,我会标注控制器或指令的使用全路径的类。例如。
4.Furthermore, 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. e.g.
/**
* @class angular_module.MyModule.MyController
*/
在这种方式,将myController的被列为一个项目在MyModule中的文档页面。
In this way, MyController will be listed as one item in MyModule's documentation page.
然后,我们可以在控制器的myController的成员函数内的注释codeS。
Then, we can annotate codes within the controller as member functions of MyController.
/**
* @name $scope.aScopeFunction
* @function
* @memberOf angular_module.MyModule.MyController
* @description
*/
在这种方式,这个功能的文档将出现在myController的的HTML页面的HTML文件。该点分隔的完整路径字符串建立连接。
In this way, this function's documentation will appear in the html file of MyController's html page. The dot-separated full path string builds the connection.
我喜欢用jsdoc因为模块服务控制器功能的层次结构保持记录angularjs codeS。它不断地jsdoc的优点在于它是一个可浏览文档站点。
I like using jsdoc to document angularjs codes because the module-service-controller-function hierarchy are kept. And it keeps jsdoc's merit that it is a browsable documentation site.
表格样式jsdoc样式表:
特别是,我已经适应了默认jsdoc样式表像Java API文档表格样式。它看起来更加清晰。
Particularly, I've adapted the default jsdoc stylesheet to a table style like the Java API documentation. It looks clearer.
在Windows上,我替换此文件: C:\\用户\\用户1 \\应用程序数据\\漫游\\故宫\\ node_modules \\ jsdoc \\模板\\ DEFAULT \\静\\风格
与此文件<一个href=\"https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css\">https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css
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
就是这样。
这篇关于JSDoc与AngularJS的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!