jsdoc | 易学教程

使用grunt-jsdoc自动化生成javascirpt文档

阅读更多关于使用grunt-jsdoc自动化生成javascirpt文档

【推荐】2019 Java 开发者跳槽指南.pdf(吐血整理) >>> 背景 Javascript已经成为一门被人们重新认识的编程语言，由于大量JS开源框架的出现，利用Javascript开发的项目越来越多，越来越大。同时，也有越来越多Javascript开发问题暴露出来，如性能、网页加载速度等，其中，Javascript文档维护也成为了开发者亟待解决的一个难题。许多现代编程语言都有自己的集成化文档生成工具，像Java有JavaDoc，.NET有NDoc，PHP有PHPDoc，这些自动化文档工具可以根据代码中的注释自动生成代码文档。 NOTE: 我个人使用的是LINUX，所以本文很多命令都是在LINUX下运作的。依赖 JsDoc 实际上， JsDoc 是一门用于标注Javascript源代码的语言。使用包含JsDoc定义的注解，程序员可以在Javascript注释中包含API文档。通过一系列工具进行批量处理，最终生成HTML或者Rich Text Format等格式的API文档。目前 JsDoc最新版本是3.0。 JsDoc Toolkit JsDoc Toolkit 是一个自动化文档工具，它是发布在Google code上的一个开源项目，和其他语言的文档工具一样，它可以自动从Javascript代码中提取注释生成格式化文档。因为JsDoc

JSDoc3 documentation of a function's argument being an array of objects?

阅读更多关于 JSDoc3 documentation of a function's argument being an array of objects?

问题 UseJSDoc.org's page on @type explains how to document arrays and objects, but not arrays of objects. My function accepts an array of objects with a specific list of properties and it's these properties that I'd like to document. The function might look like function foo(people) and the people array might have been created by the caller of the function as arr = []; arr.push({name: "Alfred", profession: "Butler", hitpoints: 2}); arr.push({name: "Batman", profession: "Vigilante", hitpoints: 42})

Use jsdoc on js with flow type annotations

阅读更多关于 Use jsdoc on js with flow type annotations

问题 When trying to process js sources with flow type annotations the jsdoc parser failes to understand the enhanced syntax! Is there a way to use jsdoc in js sources that have been enhanced with flow type annotations or what is the recommended way to generate documentation from type annotated js? 回答1: You could use babel with strip-flow-types transform and use jsdoc-babel. First, you need to install babel and related packages and jsdoc-babel on top of jsdoc. Then, create a jsdoc-conf.json file in

Is it possible to tell jsdoc to look in a file separate from the source code for documentation of that code?

阅读更多关于 Is it possible to tell jsdoc to look in a file separate from the source code for documentation of that code?

问题 I would like to keep inline comments as short as possible, since my experience is that comments of more than 3 or 4 lines tend to be glossed over, creating a lot of unnecessary "read the manual lines". I'm required by legacy to adhere to a jsdoc-compatible format for documenting code. It requires that a lot of self evident things be declared explicitly if they're to be documented correctly. Practically every tag can fall in this category. Even the ones that don't are often useless to a

How to document a factory that returns a class in angular with ngdoc?

阅读更多关于 How to document a factory that returns a class in angular with ngdoc?

问题 Given an angular app with a factory that returns a class, as such: angular.module('fooApp').factory('User', function(){ function User(name){ this.name = name; } User.prototype.greet = function(){ return "Howdy, " + this.name; } return User; }); Using ngdoc (the special flavor of jsdoc angular uses), how do I document the initializer without defining it as a method? Right now, this is what I've tried: /** * @ngdoc service * @name fooApp.User * @description User factory. */ angular.module(

What is the correct JSDoc syntax for a local variable?

阅读更多关于 What is the correct JSDoc syntax for a local variable?

问题 For a function like this... function example() { var X = 100; ... var Y = 'abc'; ... return Z; } I need to explain the purpose of some of the local variables. Adding a description like this... function example() { /** * @description - Need to explain the purpose of X here. */ var X = 100; ... /** * @description - Need to explain the purpose of Y here. */ var Y = 'abc'; ... return Z; } ...doesn't seem to be getting picked up by JS Doc v3.4.0 . What is the correct syntax? P.S. Some of my use

How can I get JSDoc to mark my param as a jQuery object?

阅读更多关于 How can I get JSDoc to mark my param as a jQuery object?

问题 I'm attempting to thoroughly comment my JavaScript and I'm using JSDoc. I have a function that consumes a jQuery object and I'd like to mark the parameter as such. Currently, I have this: /** * Initializes a login object. * @param formEl {JQuery} The login form element on the page. */ var login = function(formEl){ ... } But JSDoc doesn't recognize (or properly format) "JQuery" as a variable type. Any help? 回答1: According to http://code.google.com/p/jsdoc-toolkit/wiki/TagParam it should be

Using JsDoc3 for large apps, How to group modules into sections/categories/submodules

阅读更多关于 Using JsDoc3 for large apps, How to group modules into sections/categories/submodules

问题 I am working on an app wich will become quite huge in time. I have decided to use JsDoc3 and DocStrap to document all modules. Modules are defined via require.js and in some places they are nested up to 3 or 4 levels deep. Untill now I understand that JsDoc documentation is split into four main sections: Modules, Classes, Tutorials, Globals. Each section has a header dropdown menu and a sidebar each of them listing all of the modules in liniar fashion, alphabetically. I was wondering if there

Using JsDoc3 for large apps, How to group modules into sections/categories/submodules

阅读更多关于 Using JsDoc3 for large apps, How to group modules into sections/categories/submodules

jsDoc - how to specify array length

阅读更多关于 jsDoc - how to specify array length

问题 In jsDoc I can specify my array parameters and members like this: /** * @constructor * @param {Array.<string>} myArray */ function someFunction( myArray ){ this.firstArray = myArray; /** @member {Array.<float>} */ this.secondArray = []; } Is there also a way to specify the length , or minLength and maxLength of these arrays? 回答1: I think you're asking whether you can include the minimum/maximum length in the type expressions (for example, Array.<string> ). In short, the answer is no. You'll