假设您在ES6类(文档)中有以下代码:
/**
* @typedef Test~options
* @type {object.<string>}
* @property {array} elements - An array containing elements
* @property {number} length - The array length
*/
/**
* @param {Test~options} opt - Option object
*/
test(opt){
}
现在我想记录另一个函数,让我们给它命名test2.此函数采用完全相同的options对象,但需要另一个属性parent.
如何记录这一点而不记录冗余选项？冗余意味着:
/**
* @typedef Test~options
* @type {object.<string>}
* @property {array} elements - An array containing elements
* @property {number} length - The array length
*/
/**
* @param {Test~options} opt - Option object
*/
test(opt){ …我正在尝试使用JSDoc语法为我自己以及必须查看我的代码的人员记录我的程序.我也在努力提高自己的技能.
对于jQuery类型的参数,我有点困惑.我知道这是一个对象,但它在我的程序中相当普遍,所以我认为我应该首先为jQuery类型声明一个typedef,然后将它用作我的参数类型.所以我问,这是正确的方法吗？
/**
* DOM object referenced by jQuery
* @typedef {jQuery} $jQueryDomObject
*/
/**
* SOAP call that does ...
*
* @param {string} code Some desc ...
* @param {callback} fnctVa Some desc ...
* @param {$jQueryDomObject} $attrib Input field that ...
*/
myfunction = function (code, fnctVa, $attrib) {};
我也在SO上找到了这个问题,有点类似:
我怎样才能让JSDoc将我的param标记为jQuery对象？
我可以在单独的文件中定义所有自定义类型(例如types.jsdoc),以便它们可以在整个应用程序中重用吗？什么是正确的方法呢？
/**
* 2d coordinates.
* @typedef {Object} Coordinates
* @property {Number} x - Coordinate x.
* @property {Number} y - Coordinate y.
*/
我正在尝试使用 JSDoc 来记录我的反应状态挂钩的解构部分，例如：
const [referenceState, setReferenceState] = useState(null);
这里，referenceState是 Object 类型，并且setReferenceState需要一个 Object。
根据网上的一些信息，我正在尝试做一些事情：
/**
* @param {Object} stateToSet
* @returns {GenericArray} current state and function to change value
*/
const [referenceState, setReferenceState] = useState(null);
但这不会产生任何东西..
有人可以帮我记录referenceState一下setReferenceState吗？
从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 …当我编写以下代码时,注释器告诉我BrowserSelector在第二个typedef中没有定义:
/**
* @typedef {{name: String, minVer: Number, maxVer: Number}} BrowserSelector
*/
/**
* @typedef {{type:String, browser: BrowserSelector, attribute: Object}} Selector
*/
我认为它没有将类型与名称相关联.我怎样才能做到这一点？
我不想为它添加实际代码,只是jsdoc注释.
我目前正在重构一些我们拥有的Javascript代码,除此之外我还改变了它以利用揭示模块模式.代码看起来更整洁,它工作正常但我在大纲视图中看不到这些功能.我将顶级命名空间var视为var,但您无法展开它以查看其中的函数.
让我们说代码看起来像这样:
function myFunc1() {}
function myFunc2() {}
在这种情况下,您可以在大纲视图中看到这两个函数.但是如果你改成它:
var myNamespace = function()
{
function myFunc1() {}
function myFunc2() {}
return {
name: "myNamespace",
myFunc1: myFunc1,
myFunc2: myFunc2
}
}();
然后大纲视图只显示myNamespace var.我试过看但却找不到能够正确显示层次结构的视图.有没有人知道一种方法来查看这个或者是eclipse不能这样做的情况？
我最近开始使用jsdoc注释来记录我们的javascript代码,但是我发现@param标记的使用存在矛盾的例子.
请参阅https://code.google.com/p/jsdoc-toolkit/wiki/TagParam(PascalCase)
和https://developers.google.com/closure/compiler/docs/js-for-compiler(camel/lowercase).
camelCase对我来说很有意义:
var foo = 1;
console.log(typeof foo); // outputs "number"
什么是用于jsDoc @param评论的正确套管？或者没关系？我打算将它用于文档生成以及通过谷歌闭包运行代码以进行类型检查.
谢谢!
我正在尝试改进我的javascript代码的文档,并遵循JSDoc指南http://usejsdoc.org/.
我找不到如何记录故意的副作用.例如,以下方法:
/**
* @description
* Paints the object red.
* @return
*/
Painter.paintItRed = function(someObj){
someObj.color = "red";
};
您如何记录该方法直接作用于传递的对象的事实？一个不同的例子:
/**
* @description
* If the user has not setUp a config, show config Modal.
* @return
*/
User.checkConfig = function(user){
if(!user.config.valid){
showConfigModal();
}
};
这些是人为的例子和可能的"代码味道",但这是另一个问题.我正在研究如何记录这种行为(好的或坏的)的一些最佳实践.也许比这更好的东西//IMPORTANT!! This method is dangerous!