jsdoc
An API documentation generator for JavaScript.
Use JSDoc: Index official documentation for jsdoc 3.
Let's say you have something like the following:
var someFunc = function() {
// do something here with arguments
}
How would you correctly document that this function can take any number of arguments in JSDoc? This is my best guess, but I'm not sure it's correct.
/**
* @param {Mixed} [...] Unlimited amount of optional parameters
*/
var someFunc = function() {
// do something here with arguments
}
Related to: php - How to doc a variable number of parameters
Source: (StackOverflow)
Given a Javascript function that takes callback functions as parameters:
var myFunction = function(onSuccess, onFailure) {...}
How do I document onSuccess's return type and arguments?
Source: (StackOverflow)
Is there documentation for what JSDoc subset, superset, or mix of the two IntelliJ supports? My motivation for using JSDoc is two-fold:
- For developers: so IntelliJ can provide better code-completion, code checking, error checking, etc.
- For runtime efficiency: using the Closure compiler.
For #1 above, it is important for me to use JSDoc markup that is supported by IntelliJ, and until now figuring this out has mostly been a trial and error process.
Source: (StackOverflow)
I want to indicate that a parameter should be a DOM node, but I can't seem to find any information about how to indicate that with jsDoc. I could just use {Object}, but that is rather ugly. I would much rather have something like {Node} or {DOMNode}, but I can't find any examples to point me in that direction.
So, how do I mark a parameter as expecting a DOM node?
Source: (StackOverflow)
The @param tag allow the documentation of properties, e.g.
/**
* @param {Object} userInfo Information about the user.
* @param {String} userInfo.name The name of the user.
* @param {String} userInfo.email The email of the user.
*/
How would I document the properties of the @this tag?
/**
* @this {Object}
* @param {String} this.name The name of the user.
* @param {String} this.email The email of the user.
*/
I'm wondering if anyone working on the project knows. (The docs are still being created...)
Thanks
Matt
Source: (StackOverflow)
I need to choose a documentation generator (similar to jdoc in java or rdoc in ruby) for my javascript project that (built with jquery, underscore and backbone)
Candidates:
Requirements
- should work with jquery, underscore and backbone. that means object-literal methods etc
- I really like pdoc but its too centered around prototype, poorly documented, and I don't want to make extra files (sections?) to make it work (not sure about this)
- docco is nice but I want structured output (as in menu + class/func structure like jdoc)
- must be command line/makefile compatible (not web pastie)
Tips, tricks, tutorials, success stories, advice greatly welcomed.
Why Doesn't jQuery use JSDoc?
Source: (StackOverflow)
I have some code written in CoffeeScript and I want to optimize the generated JavaScript with the Google Closure Compiler, so these files need to be documented with JSDoc.
My question is, how can I document the *.coffee files to generate javascript containing working JSDoc for the closure compiler?
One more question: is there a way to keep a single-line comment in *.coffee ?
Source: (StackOverflow)
According to the JSDoc wiki for @param you can indicate a @param is optional using
/**
@param {String} [name]
*/
function getPerson(name) {
}
and you can indicate a param inline using
function getPerson(/**String*/ name) {
}
And I can combine them like the following, which works ok.
/**
@param [name]
*/
function getPerson(/**String*/name) {
}
But I would like to know if there is a way to do it all inline if possible.
Source: (StackOverflow)
Or do they and it's just not in the source? I'd really like to get something that will stop js-doc-toolkit from freaking out each time it parses jQuery. It also means I can't properly document any code using jQuery as a dependency without at least putting some boilerplate js-doc blocks, which fail to properly document jQuery's structure. Is there a common solution I'm not aware of? I have tried googling, btw.
Source: (StackOverflow)
I want to be able to take JSDoc comments like this anywhere in JavaScript source (even nested down several layers of functions, in a module or even anonymous functions):
/**
* Used to do some important thing that needs doing that works like xyz.
* @param {String} whatever - some string that has some purpose
* @param {Function} callback - a function that needs to be run
* @returns {Boolean} whether or not something happened
*/
function something(whatever, callback) {
...
and have some easy way to produce nice markdown:
##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.
*Parameters*
`whatever {String}` some string that has some purpose
`callback {Function}` a function that needs to be run
*Returns*
`{Boolean}` whether or not something happened
Where "root" is the namespace at which that function is reachable. Or if it's an anonymous function or a private function (that for some reason should be in public doco, does that even make sense??), use some other convention to denote that. Maybe
##_private_function_ `something(whatever,callback)`
and
##_anonymous_function_`(whatever,callback)`
It doesn't have to be exactly that format, just something that looks good on Github and makes sense. The ideal tool would be smart enough to be able to take code like Mustache.js and produce good output. And extra good would be if it can handle lots of source files and produce one document as output, or a linked set of documents depending on configuration.
And it would be best if this was done in a way that can be fully and easily included in a git repo so that people don't need to set up a highly specific toolchain to update the doco. Or require a minimal toolchain at least.
Oh, and a pony.
Existing options
JSDoc, plus some kind of HTML -> markdown conversion
JSDoc is pretty good. But I can't seem to make it work well with modules. Or rather, it's a bigger hassle than it ought to be IMHO. I shouldn't need to add an extra tag to name the function. I've tried the @export and @name and still have trouble getting it to show up in the final doc the way I'd want. If someone can point to a JSDoc commented source that has modules in it and is done well, that might help. Update: JSDoc v3 actually seems much better with modules than v2 so this might be a better fit.
Even if I could get JSDoc output like I want, I'd need to convert from HTML to markdown. I can't seem to find a good tool for that, does one exist?
I played a bit with Docdown but the fact it's PHP is kind of a nonstarter for me...
YUIDoc, plus conversion
I actually haven't played with YUIDoc but it looks ok. Still, I would need a converter. Does it deal with modules easily and avoid having to supply the function name and export name explicitly?
Dox, plus markdown templates
Dox produces JSON as it's output, so then you'd need to marry that to some good markdown templates, and plus include a template engine to generate the documents. Has anyone put together a set of such templates in a useful fashion?
jGrouse, plus conversion
Runs with ANT. Next...
ScriptDoc...
Does this even exist anymore? Seems to be part of Aptana studio so that would be a nonstarter... Aptana doesn't seem to any info on it. But ScriptDoc.org has some interesting information on crack, if that's helpful...
Pdoc is Ruby based but that toolchain is not uncommon so that's not a huge problem. You can provide your own templates so maybe there are already some good markdown ones. I haven't played with it... is it worthwhile? Are there good markdown templates out there?
Something else?
What else is out there?
Make your own!
After messing around with JSDoc for a few hours trying to make it work how I wanted, I gave up and wrote my own quick and dirty solution in Java for CharFunk, a unicode JavaScript library I've been working on. It works well enough for what I need though it's not close to general purpose yet.
So.....
Is this an unmet need or is it just me?
Source: (StackOverflow)
Edit: This is technically a 2 part question. I've chosen the best answer that covers the question in general and linked to the answer that handles the specific question.
What is the best way to document anonymous objects and functions with jsdoc?
/**
* @class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* @param {PageRequest} pageRequest Info on the page you want to request
* @param {function} callback Function executed when page is retrieved
*/
this.getPage = function(pageRequest, callback) {
};
};
Neither the PageRequest object or the callback exist in code. They will be provided to getPage() at runtime. But I would like to be able to define what the object and function are.
I can get away with creating the PageRequest object to document that:
/**
* @namespace {PageRequest} Object specification
* @property {String} pageId ID of the page you want.
* @property {String} pageName Name of the page you want.
*/
var PageRequest = {
pageId : null,
pageName : null
};
And that's fine (though I'm open to better ways to do this). [Answer]
What is the best way to document the callback function? I want to make it know in the document that, for example, the callback function is in the form of:
callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)
Any ideas how to do this? [Answer]
Source: (StackOverflow)
I have some code that returns a promise object, e.g. using Q library for NodeJS.
var Q = require('q');
/**
* @returns ???
*/
function task(err) {
return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}
How to document such a return value using JSDoc?
Source: (StackOverflow)
Has anyone ever documented BackboneJS code with JSDoc?
I'm having problems annotating Backbone constructs such as:
User = Backbone.Model.extend({
defaults: { a: 1 },
initialize: function () {
// ...
},
doSomething: function (p) {
// ...
}
});
Any advice appreciated. Thanks.
Source: (StackOverflow)
Do you know if there is a some sort of <code> tag in JSDoc?
I need to add pieces of code in my documentation like this:
/**
* This function does something see example below:
*
* var x = foo("test"); //it will show "test" message
*
* @param {string} str: string argumnet that will be shown in message
*/
function foo(str)
{
alert(str);
}
I need the code in the comments to be displaied by JSDoc as code (if not sintax highlighetd, at least like preformatted or something with grey background)
Thanks.
Source: (StackOverflow)
I have 2 types of Modules:
Require.js Main File:
require.config({
baseUrl: "/another/path",
paths: {
"some": "some/v1.0"
},
waitSeconds: 15,
locale: "fr-fr"
});
require( ["some/module", "my/module", "a.js", "b.js"],
function(someModule, myModule) {
}
);
Mediator Pattern:
define([], function(Mediator){
var channels = {};
if (!Mediator) Mediator = {};
Mediator.subscribe = function (channel, subscription) {
if (!channels[channel]) channels[channel] = [];
channels[channel].push(subscription);
};
Mediator.publish = function (channel) {
if (!channels[channel]) return;
var args = [].slice.call(arguments, 1);
for (var i = 0, l = channels[channel].length; i < l; i++) {
channels[channel][i].apply(this, args);
}
};
return Mediator;
});
How can i document this with jsdoc3 when possible with jsdoc too?
Source: (StackOverflow)