带有 AngularJS 的 JSDoc [英] JSDoc with AngularJS
问题描述
目前在我的项目中，我们正在使用 JSDoc，我们最近开始实施 Angular，我想继续使用 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?
推荐答案
我也遇到过这个问题.我现在正在通过这样的 jsdoc 注释为 angularjs 代码编写文档:
I have encountered this issue as well. I am now writing documentation for angularjs codes through jsdoc comments like this:
1. 制作一个空白的 .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.在定义任何新角度模块的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' 编写输入参数的文档，并使用 '@return' 返回值.
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.如果我在 MyModule 的控制器或指令中有很长的代码并且想要有一个单独的 html 文件来记录它，我将使用完整路径将控制器或指令注释为一个类.例如
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. 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 的成员函数.
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.
namepath 有三种类型的语法:
There are three types of syntaxes for namepath:
- Person#say//名为say"的实例方法.
- Person.say//名为say"的静态方法.
- Person~say//名为say"的内部方法.
然而，将控制器注释为类的一个不完善之处在于，在生成的 html 文档中，控制器名称之前会发现一个新"，因为它被描述为类构造函数.
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.
此外，您可以定义命名空间以添加层次结构.例如，您可以定义一个命名空间来包含所有控制器
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
*/
，并为所有控制器添加 MyApp.Controllers 前缀.您还可以定义名称空间，如 MyApp.Product 或 MyApp.Customer 等.
, and prefix all controller with MyApp.Controllers. You can also define namespaces like MyApp.Product or MyApp.Customer etc.
虽然不完美，但我喜欢使用 jsdoc 来记录 angularjs 代码，因为
Although not perfect, I like using jsdoc to document angularjs codes because
- 很简单；
- 保持模块-控制器-功能层次结构；
- 它保留了 jsdoc 的优点，即它是一个可浏览的文档站点.
表格样式 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:\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
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
就是这样.
这篇关于带有 AngularJS 的 JSDoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
