如何告诉JSDoc有关返回的对象的结构.我找到了@return {{field1: type, field2: type, ...}} description语法并试了一下:
/**
* Returns a coordinate from a given mouse or touch event
* @param {TouchEvent|MouseEvent|jQuery.Event} e
* A valid mouse or touch event or a jQuery event wrapping such an
* event.
* @param {string} [type="page"]
* A string representing the type of location that should be
* returned. Can be either "page", "client" or "screen".
* @return {{x: Number, y: Number}}
* The location of the event
*/
var getEventLocation …javascript documentation-generation code-documentation jsdoc jsdoc3
我花了很长时间在互联网上寻找使用jsdoc正确记录回调的最佳方法,但遗憾的是,我还没有找到一个好的.
这是我的问题:
我正在为开发人员编写Node.js库.该库提供了开发人员将使用的多个类,函数和方法.
为了使我的代码清晰易懂,以及(希望)将来自动生成一些API文档,我已经开始在我的代码中使用jsdoc来自我记录正在发生的事情.
假设我定义了如下函数:
function addStuff(x, y, callback) {
callback(x+y);
});
使用jsdoc,我目前正在记录此函数,如下所示:
/**
* Add two numbers together, then pass the results to a callback function.
*
* @function addStuff
* @param {int} x - An integer.
* @param {int} y - An integer.
* @param {function} callback - A callback to run whose signature is (sum), where
* sum is an integer.
*/
function addStuff(x, y, callback) {
callback(x+y);
});
我觉得上面的解决方案有点像hack-ish,因为我无法用绝对术语来指定回调函数应该接受什么.
理想情况下,我想做的事情如下:
/**
* Add two …我一直在尝试使用JSDoc3来生成文件的文档,但是我遇到了一些困难.该文件(Require.js模块)基本上如下所示:
define([], function() {
/*
* @exports mystuff/foo
*/
var foo = {
/**
* @member
*/
bar: {
/**
* @method
*/
baz: function() { /*...*/ }
}
};
return foo;
}
问题是,我无法baz在生成的文档中显示出来.相反,我只获得一个foo/foo模块的文档文件,该文件列出了一个bar成员,但bar没有baz(只是一个foo源代码的链接).
我已经尝试改变bar指令了@property,我已经尝试将baz指令更改为@member或@property,但这些都没有帮助.无论我做什么,巴兹似乎都不想表现出来.
有谁知道我可以用什么指令结构让baz出现在生成的文档中？
PS我试过在JSDoc网站http://usejsdoc.org/howto-commonjs-modules.html上阅读这样的页面,但它只描述了案例foo.bar,而不是foo.bar.baz.
目前在我的项目中我们使用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()提供任何想法的文档？
是否可以使用枚举作为JSDoc @param类型声明,如下例所示？
/**
* @enum { Number }
*/
var TYPES = {
TYPE_A: 1,
TYPE_B: 2
}
/**
* @param { TYPES } type
*/
function useTypesEnum( type ) {
}
如果我使用Eclipse之类的IDE等JavaScript,那么应该不会引发警告？
我正在使用JSDoc进行参数文档.
很清楚如何记录参数类型many_prompts,但是记录它返回的函数的正确方法是什么？
/**
* @param {Number} - number of times to prompt
* @return {Function(prompt{Number})} - the returned function
*/
function many_prompts(count) {
return function(prompt) {
for(var i=0; i < count; i++) alert(prompt);
}
}
//Example of use:
var y =many_prompts(3);
y('Hello World');
从Node.js运行基本的JSDoc编译/渲染之后:
jsdoc file1.js file2.js
我使用目录"out"中的默认模板获得格式良好的文档.几乎所有都如预期!
但是在打开文档时,它总是在index.html页面上显示"Home",在该初始页面上没有内容,并且在侧边栏导航中显示"Home".
我如何以及在何处注明项目名称以取代"Home"？我还想看一个项目描述,以及作者和版权信息.
这似乎是JSDoc中最基本的事情,但我无法找到这些信息!基于我在互联网上发现的一些随机文章,我尝试了以下内容:
/**
* This JavaScript file contains foo bar baz...
*
* @projectname Project Name
* @version 0.1
* @author Greg Pettit
* @copyright 2015
*
*/
但我没有爱.
[编辑添加:]
发现了@file/@fileOverview/@overview(所有同义词)指令,这有点帮助,因为我现在可以为每个文件描述和设置版权/作者信息:
/**
* @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
*
* @version 0.1
* @author Greg Pettit
* @copyright 2015
*
*/
这留下了两个"问题"来解决:
概述说明; 我认为@file可以满足我的大多数需求,但由于它是每个文件,我仍然会喜欢在包含文件的描述之前出现的"简介"类型段落或概述段落.
用自定义文本替换"Home"文本
如何使用具有以下形式的jsdoc来记录API(单个文件)
// api.js
exports.addSocketEvents = function(socket) {
/**
* This will do that and ...
* @param {Object} data Some data
* @param {string} data.bla Something about bla
* @param {number} data.n Some number
*/
socket.on('something_1', function(data) { ... });
/**
* Another function that will do ..
* @param {string} id of something
*/
socket.on('something_2', function(id) { ... });
...
};
exports.addRoutes = function(app) {
/**
* PATCH /something/:id/juhu
* Will do this and that and will respond with …我正在寻找一种工具来生成JavaScript函数和属性的文档,即使没有与这些函数或属性相关的适当格式化的注释块(如Doxygen那样).
JSDoc和其他一些文档工具之间的比较提到JSDoc可以解析源代码以生成文档,即使没有注释块(像Doxygen,如上所述).他们说所有其他工具只解析注释块.
我根据这条指令从npm(在节点上)安装了JSDoc 3.3.0-alpha4 ,我正在尝试为我的项目生成文档.据我所知,JSDoc不会为没有相关JSDoc标志的正确注释的函数或属性生成任何文档.
我知道JSDoc经历了多次迭代,是否已删除此功能或我没有使用正确的交换机？我试图检查命令行选项,但找不到任何开关.我只是这样使用它:
./node_modules/.bin/jsdoc -r -l my_project --destination doc/
我知道还有其他工具可以自动为代码添加文档块,例如smartcomments,但这并不是我想要的.任何人都可以对此有所了解吗？
我一直在尝试使用JSDoc记录以下代码:
/**
* @module person
*/
/**
* A human being.
* @class
* @param {string} name
*/
function Person(name){
this.name = name
}
Person.prototype = new function(){
var amount_of_limbs = 4;
/**
* Introduce yourself
*/
this.greet = function(){
alert("Hello, my name is " + this.name + " and I have " + amount_of_limbs + " limbs");
}
}
但是greet在最终的JSDoc文档中找不到该方法.我究竟做错了什么？
javascript documentation-generation code-documentation jsdoc jsdoc3