jsdoc / jsdoc Goto Github PK
View Code? Open in Web Editor NEWAn API documentation generator for JavaScript.
Home Page: https://jsdoc.app/
License: Apache License 2.0
An API documentation generator for JavaScript.
Home Page: https://jsdoc.app/
License: Apache License 2.0
jsdoc/main.js", line 120: exception from uncaught JavaScript throw: Configuration file cannot be evaluated. ReferenceError: "JSON" is not defined.
Do not have another version of Rhino installed, so not sure what this error would be.
When inside a requirejs module, functions declared as functions instead of vars won't have their prototyped methods documented.
I'm not sure if this is the case outside of modules/exports
This does not work: (the myClass.myMethod is not documented)
define(['some/module'],
/** @exports some/otherModule */
function () {
/**
* My Class is cool
* @class
*/
function myClass() {}
/**
* My method, also cool
*/
myClass.prototype.myMethod = function () {};
return new myClass();
}
);
This works: (the myClass2.myMethod is documented)
define(['some/module'],
/** @exports some/otherModule2 */
function () {
/**
* My Class is cool
* @class
*/
var myClass2 = function() {}
/**
* My method, also cool
*/
myClass2.prototype.myMethod = function () {};
return new myClass2();
}
);
I'm trying to write my own template for jsdoc3 and wanted to do some logging in publish.js
in the default template. I placed my JavaScript file in the same directory as the jsdoc unix executable and can run ./jsdoc file.js
to get an out directory and documentation within it. I'm also able to run the example usage for non-mac users:
java -cp lib/js.jar org.mozilla.javascript.tools.shell.Main \
-modules node_modules -modules rhino_modules \
jsdoc.js -T
However when I copy the debug command from the readme's debugging section and replace your/script.js
with file.js
I get this error:
Exception in thread "main" java.lang.NoClassDefFoundError: org/mozilla/javascript/tools/debugger/Main
Caused by: java.lang.ClassNotFoundException: org.mozilla.javascript.tools.debugger.Main
at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
I must be missing a step but didn't see where I was tripped up.
It would be nice if 1: I didn't have to use @Lends everywhere for my structure and 2: functions without doc-blocks being returned as part of an object literal (or other variants) would still be documented. There was better support for this in v2. I realize these 2 tasks may not necessarily coincide, but the latter is much more annoying (as it involves a lot more edits than the former).
var myUtil = (function(){
/** @lends myUtil */
return {
/**
* This gets added
*/
getItem: function() {},
setItem: function() {
// This doesn't
}
};
})();
Namespace descriptions are used as the name.
If the namespace doesn't have a description, but uses dot notation (jv.Apply) only the last item is used. This is fine, except it makes it difficult to track it's parent in the generated docs.
Functions inside the namespace are being thrown under global instead of the namsepace.
I switched from 2 to 3 and regenerated my docs and have had a few steps backwards as far as results go.
Here is some example code:
jv.Util = (function(){
// PRIVATE
var _ajaxCache = {};
return {
months: [
"December"
],
/**
* Utility wrapper for $.ajax();
*
* args.ajaxType is required, must be unique
* @example jv.UTIL.ajax({ ajaxType: 'test', url: 'profile/mine' });
* @param {Object} args (required)
* @type $.Deferred()
*/
ajax: function(args) {
}
};
})();
jv.Factory = (function() {
// PRIVATE
/**
* Cached flags of which assets & resources have already been loaded
*/
var assets = {};
// PUBLICLY VISIBLE
return {
/**
* Loads all resources specified and issues callback upon completion
*
*/
resource: function(resourceNames, callback) {
},
/**
* Loads the asset from jv.Assets if it hasn't been loaded already
* Assets SHOULD load instantly and not require callbacks
*
* @param assetName string The name of the plugin to load
* @param force boolean [false]: Set to true to ignore previous loads
*/
asset: function(assetNames, force) {
}
};
})();
/**
* @namespace Asset functions intended to only be used internally by the factory
*/
jv.Assets = {
/**
* Run to initialize batch features on tables
*
* Give a form class `batch` and place a checkbox into a <th> for all or use classes `a.checkAll` and `a.uncheckAll` links
* Compatible with dynamically generated rows
* Adds class `checked` to <th>
*/
tableCheckboxes: function() {
},
/**
* Enables HTML5 Placeholders and validation
*/
forms: function() {
}
};
If the exports statement defining a class in a CommonJS module is not the first token/string on a line, then the class isn't properly generated in the output. e.g.
This generates good output:
/**
Document me.
@module pkg/myobject
*/
/**
Document me.
@class
*/
exports.MyObject = Object.create({}, /** @lends module:pkg/myobject.MyObject# */ {
/**
Function that makes foo
@function
*/
myFunc: {
value: function () {
// function definition
}
},
});
But this does not:
/**
Document me.
@module pkg/myobject
*/
/**
Document me.
@class
*/
var MyObject = exports.MyObject = Object.create({}, /** @lends module:pkg/myobject.MyObject# */ {
/**
Function that makes foo
@function
*/
myFunc: {
value: function () {
// function definition
}
},
})
JSDoc Toolkit uses the -p option, this should be ported to JSDoc 3.
Is this a possible tool for the JSDoc 3 project?
[ reported by Lea Hayes http://groups.google.com/group/jsdoc-users/browse_thread/thread/4b92f74391400705 ]
Is the following valid? fooo isn't being added to the module, instead
I have to add @memberof module:my/module to every single thing.
/**
/**
}) ();
I'm using JSDoc 3. With the default output template, the class names in the navigation (right-hand nav) are not sorted alphabetically, although the modules are sorted alphabetically.
Lots of JavaScript minifiers preserve comments that preceed with /*!
Unfortunately this means that either:
It would be nice if those two projects could play nice together. For most applications only the initial occurrence of /*!
would be needed for the file blurb. Perhaps the alternative /*!!
could be used to avoid accidental use of /*!
as doclet?
/*!!
* Script that does something awesome
*
* @copyright (c) 2011 Rotorz Limited. All rights reserved.
* @author Lea Hayes
* @module myscript/core
*/
/**
* My function
*/
function foo() { ... }
I know this isn't proper usage but...
/**
* @property
*/
var foo = "bar";
Results: org.mozilla.javascript.EcmaError: TypeError: Cannot read property "description" from undefined...
Expected: Some kind of warning message indicating the problem...e.g., @Property tag requires etc...
Is there a feature that would allow jsdoc to be associated with a namespace that is generated dynamically?
I am not sure if the following is valid, but perhaps this could be a feature request?
/**
* My special namespace
*
* @name my.namespace
* @namespace
*/
$namespace('my.namespace', /** @lends my.namespace **/ {
/**
* Foo - does something really neat...
* @function
*/
foo: function() {
}
});
Just to clarify, the above is used as follows:
my.namespace.foo();
It would be nice to be able to explicitly include and exclude specific files and directories. The syntax could be something like:
{
includeDirs: [
"/Users/johndoe/Documents/jsapplication",
"./util/"
],
excludeDirs: [
"/Users/johndoe/Documents/jsapplication/lib",
"./util/tests/"
],
include: [
"/Users/johndoe/Downloads/example.js",
],
exclude: [
"/Users/johndoe/Documents/jsapplication/r.js",
"./example2.js"
]
}
Hi,
In my current application, I've multiple namespaces, each of one containing classes, mixins, and sub-namespaces.
When I generate the doc, I've got this in my side pannel. As you can see, everything is messed : I can't know from a single eye shot if the class Array is in the GUI or LIB namespaces (in fact, it's in MixinUtils ...).
I think it could be a problem for large applications. Unfortunately, I currently don't know how to pretty print these informations.
CrashReportScreen
FlatScreen
ProgressScreen
WebGLInfoScreen
Array
Object
GUI
BrowserUtils
LIB
ClassUtils
MixinUtils
EventBehavior
StoreBehavior
VolatileBehavior
WidgetBehavior
I caused title's issue.
command:
java -classpath js.jar org.mozilla.javascript.tools.shell.Main jsdoc.js -e UTF-8 test.js
JS file example:
/**
* @namespace テスト
*/
window.Test = {
// dummy
};
"テスト" mean "Test" in Japanese Katakana.
Broken "テスト" string in output HTML file.
environment:
When documenting members of an object literal as a class, the line numbers in the source are reported as the start of the object literal rather than the location of the property or method being documented.
Example:
/**
* Some description
* @class SomeController
* @extends AppController */
var SomeController = /** @lends SomeController */ { // line 5
/** @memberOf SomeController */
name: 'SomeController',
/** Some method
* @param {Number} someParam
*/
someMethod: function( someParam ) { // line 12
.....
}
};
Note: I realise that @memberof isn't required in this instance to get jsdoc to generate documentation, however Eclipse does not recognize the class without it.
The generated documentation will state that SomeController.someMethod is on line 5, not on line 12. When dealing with files with 6000+ lines, it would be nice to have the correct line number (especially since I'm generating a link to our source repository via Trac).
Hi is it possible to have a hook that allows a plugin to manipulate the raw source code before it is passed to the parser?
I would like to do some regex based replacements not directly to any symbol symbolFound
detects. I think this could be a quite powerful feature for plugins.
Do you see a problem with adding this?
Using double-quotes to enclose non-legal characters, or string-indexed names in code.
I'm documenting some code that contains the following construct:
(function myFunc(name) {
if (isTrue("foo")) {
return foo;
}
})(obj)[prop] = true;
This is a simplified version of the actual code but if you run jsdoc on it, it raises an exception (see below for full strack trace). Note that there is no error if:
You remove the inner if() statement, or make the if() expression a non-function.
if (bar) {
return foo;
}
You remove the (obj)[prop] after the closing paren for the immediate function:
(function myFunc(name) {
if (isTrue("foo")) {
return foo;
}}) = true;
Stack trace below:
$ ./jsdoc test.js
org.mozilla.javascript.EcmaError: TypeError: Cannot call method "replace" of undefined (/Users/wnpm38/jsdoc/lib/require.js#34(Function)#13(Function)#14(Function)#171)
at org.mozilla.javascript.ScriptRuntime.constructError(ScriptRuntime.java:3785)
at org.mozilla.javascript.ScriptRuntime.constructError(ScriptRuntime.java:3763)
at org.mozilla.javascript.ScriptRuntime.typeError(ScriptRuntime.java:3791)
at org.mozilla.javascript.ScriptRuntime.typeError2(ScriptRuntime.java:3810)
at org.mozilla.javascript.ScriptRuntime.undefCallError(ScriptRuntime.java:3829)
at org.mozilla.javascript.ScriptRuntime.getPropFunctionAndThisHelper(ScriptRuntime.java:2334)
at org.mozilla.javascript.ScriptRuntime.getPropFunctionAndThis(ScriptRuntime.java:2327)
at org.mozilla.javascript.Interpreter.interpretLoop(Interpreter.java:1514)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function)#13(Function)#14(Function):171)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function)#13(Function)#14(Function):50)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function)#13(Function):49)
at script.newSymbolDoclet(/Users/wnpm38/jsdoc/lib/require.js#34(Function):99)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function):35)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function)#24(Function):24)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function)#24(Function):43)
at script.visitNode(/Users/wnpm38/jsdoc/lib/require.js#34(Function):264)
at org.mozilla.javascript.Interpreter.interpret(Interpreter.java:854)
at org.mozilla.javascript.InterpretedFunction.call(InterpretedFunction.java:164)
at org.mozilla.javascript.JavaAdapter.doCall(JavaAdapter.java:598)
at org.mozilla.javascript.JavaAdapter.callMethod(JavaAdapter.java:573)
at adapter1.visit()
at org.mozilla.javascript.ast.InfixExpression.visit(InfixExpression.java:209)
at org.mozilla.javascript.ast.ExpressionStatement.visit(ExpressionStatement.java:152)
at org.mozilla.javascript.ast.ScriptNode.visit(ScriptNode.java:347)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at org.mozilla.javascript.MemberBox.invoke(MemberBox.java:161)
at org.mozilla.javascript.NativeJavaMethod.call(NativeJavaMethod.java:247)
at org.mozilla.javascript.Interpreter.interpretLoop(Interpreter.java:1701)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function):107)
at script(/Users/wnpm38/jsdoc/lib/require.js#34(Function):65)
at org.mozilla.javascript.Interpreter.interpret(Interpreter.java:854)
at org.mozilla.javascript.InterpretedFunction.call(InterpretedFunction.java:164)
at org.mozilla.javascript.optimizer.OptRuntime.call2(OptRuntime.java:76)
at org.mozilla.javascript.gen.__jsdoc_js_1._c_main_5(./jsdoc.js:204)
at org.mozilla.javascript.gen.__jsdoc_js_1.call(./jsdoc.js)
at org.mozilla.javascript.optimizer.OptRuntime.callName0(OptRuntime.java:108)
at org.mozilla.javascript.gen.__jsdoc_js_1._c_script_0(./jsdoc.js:82)
at org.mozilla.javascript.gen.__jsdoc_js_1.call(./jsdoc.js)
at org.mozilla.javascript.ContextFactory.doTopCall(ContextFactory.java:426)
at org.mozilla.javascript.ScriptRuntime.doTopCall(ScriptRuntime.java:3178)
at org.mozilla.javascript.gen.__jsdoc_js_1.call(./jsdoc.js)
at org.mozilla.javascript.gen.__jsdoc_js_1.exec(./jsdoc.js)
at org.mozilla.javascript.tools.shell.Main.evaluateScript(Main.java:654)
at org.mozilla.javascript.tools.shell.Main.processFileSecure(Main.java:552)
at org.mozilla.javascript.tools.shell.Main.processFile(Main.java:507)
at org.mozilla.javascript.tools.shell.Main.processSource(Main.java:499)
at org.mozilla.javascript.tools.shell.Main.processFiles(Main.java:215)
at org.mozilla.javascript.tools.shell.Main$IProxy.run(Main.java:134)
at org.mozilla.javascript.Context.call(Context.java:521)
at org.mozilla.javascript.ContextFactory.call(ContextFactory.java:535)
at org.mozilla.javascript.tools.shell.Main.exec(Main.java:198)
at org.mozilla.javascript.tools.shell.Main.main(Main.java:174)
I wonder if it might be possible to introduce a Table of Contents (@toc) tag to the syntax that JSDoc parses? The use case for this tag would be for templates to be able to construct an index page which shows the various modules which have been documented. I guess the easy implementation is simply "@toc Module Name", however, I wonder if it might be possible to introduce some kind of hierarchy, so we could have sub-modules etc. I'm not 100% sure what the syntax for this should be though - perhaps "@toc {Module Name 1} Sub-module 1", so the part in braces is just a reference. Does this scale down to sub-sub-modules with the JSDoc syntax for tags - i.e. can you do something like "@toc {1} {2} {3} 4"?
Add a @source tag, to allow the user to specify any source they wanted (ignoring the actual source metadata).
As reported by Laurie Harper:
I tried running JsDoc3 against a project of mine, and it crashed; I tracked the crash down to an unsafely
guarded use of index[doc.longname].push() in main.js (the code checks first if index[doc.longname] is
falsey and initializes it to an array, but if doc.longname matches a name from Object.prototype, such as
'constructor' in this case, the test isn't sufficient)."
Hi,
Is there any nice way to get all self.methods and properties documented?
/** @class*/
var myClass = function() {
/** Document me. */
this.method = function() {};
var self = this;
/** Document me. */
self.anotherMethod = function() {};
/** Document me. */
self.prop= 1;
};
A custom of a framework I'm documenting involves using dots (.) in folder names, like a "folder extension" so to speak. For instance:
lib/folder.fun
The folder named "folder.fun" contains the JavaScript file that exports the symbol (Funclass, in this case)
lib/folder.fun/funclass.js
I tagged the class like this:
@Class module:lib/folder.fun.Funclass
Thhe full module name is not picked up by the parser (I'm assuming) due to the dot in the folder name. The actual output names the module "fun" instead of the desired "lib/folder.fun".
This should be similar to the support in JSDoc Toolkit.
/**
* @namespace
* @property {Object} defaults The default values.
* @property {Number} defaults.a The a property of the defaults.
* @property {String} defaults.b The b property of the defaults.
* @property {Boolean} defaults.c The c property of the defaults.
*/
myobject = {
defaults: {
a: 1,
b: "Hit the light",
c: true
}
};
Currently JSDoc ignores @inheritDoc
and @override
tags, however it would be nice to replace them with superclass's (modified in case of @overrride
tag) docstrings in HTML documentation.
In jsdoc v2, @constructs
would infer the current class based on the containing @class
or @lends
.
In jsdoc v3, this is not the case anymore and @constructs
requires an explicit class name specification or it blows up with
js: "./jsdoc.js", line 87: exception from uncaught JavaScript throw: TagValueRequiredError: The @constructs tag requires a value. File: $file, Line: $line
undefined
This forces jsdoc on classes to be even more repetitive when using class patterns &etc… involving @lends
: the class name now has to be specified for the class, in @lends
and in @constructs
.
This new restriction is also undocumented on http://usejsdoc.org/ (though to be fair, there's no documentation at all for @constructs
currently)
Sometimes in RequireJS modules I define a local variable in the same statement that exports a function. This appears to confuse JSDoc as it does not recognize the exported symbol as being exported.
File1
/** @exports file1 */
define(function(){
var exports={}
/** @constructor */
var someObject = exports.someObject = function() {}
someObject.prototype.whatever=function() {}
return exports
})
JSDoc cannot resolve the reference to module:file1.someObject
in the @augments
tag in
File 2
/** @exports file2 */
define(function(){
var exports = {}
var file1 = require("./file1")
/**
* @constructor
* @augments module:file1.someObject
*/
exports.otherObject = function() {}
return exports
})
This is not a critical, or truly breaking issue since the same thing can be accomplished via
/** @constructor */
exports.someObject = function() {}
var someObject = exports.someObject
But it would be nice if at some point it was supported.
When documenting this code:
function dosomething(canvas) {}
The output includes
Do something with a <canvas> tag
</p>
So the browser will actually show a canvas.
I believe output should be escaped with something like
Reported by malcolm.player:
I get the following errors. I am running this on windows 7 64bit
C:\Libaries\micmath-jsdoc-f742159>dir
Volume in drive C has no label.
Volume Serial Number is 541B-3397
Directory of C:\Libaries\micmath-jsdoc-f742159
04/25/2011 06:11 PM <DIR> .
04/25/2011 06:11 PM <DIR> ..
04/12/2011 03:02 PM 33 .gitignore
04/25/2011 06:02 PM <DIR> build-files
04/12/2011 03:02 PM 2,524 build.xml
04/12/2011 03:02 PM 0 changes.md
04/12/2011 03:02 PM 199 conf.json
04/12/2011 03:02 PM 119 jsdoc
04/25/2011 06:11 PM 1,210 jsdoc.jar
04/12/2011 03:02 PM 8,231 LICENSE.md
04/12/2011 03:02 PM 7,889 main.js
04/25/2011 06:02 PM <DIR> modules
04/12/2011 03:02 PM 738 package.json
04/25/2011 06:02 PM <DIR> plugins
04/12/2011 03:02 PM 2,842 README.md
04/25/2011 06:02 PM <DIR> templates
04/25/2011 06:02 PM <DIR> test
10 File(s) 23,785 bytes
7 Dir(s) 231,436,898,304 bytes free
C:\Libaries\micmath-jsdoc-f742159>java -jar jsdoc.jar --test
js: Couldn't read source file "\/main.js: \\main.js (The specified
path is invalid)".
Doesn't appear to be a way to return to this (or some sort of home page/overview page)
Hello,
Code related : https://gist.github.com/ffb1b5829f26ca6b4936
When this file's documentation is generated, the two @fires links point to the methods instead of the events.
Thanks,
It'd be really useful if Markdown formatting (and not just HTML) were supported, as it is in other common documentation libraries.
Hi,
this is probably parser issue, but maybe there is any nice workaround, without adding semicolons everywhere.
/** This works.*/ this.test = function(){}
/** This don't. */ this.test2 = function(){};
//--
/** This works.*/ this.test = function(){}
/** This works. */
this.test2 = function(){};
//--
/** This works.*/ this.test = function(){};
/** This works. */ this.test2 = function(){};
The following will correctly create an Array page with a dispatchChangeEvent() method.
/**
@external Array
*/
/**
@function external:Array.dispatchChangeEvent
*/
Object.defineProperty(Array.prototype, "dispatchChangeEvent", {value: false, enumerable: false});
But if you change @function to @Property, the documented property is added to to the Global namespace in the HTML output.
/**
@external Array
*/
/**
@property external:Array.dispatchChangeEvent
*/
Object.defineProperty(Array.prototype, "dispatchChangeEvent", {value: false, enumerable: false});
Results: The Array page has no members.
Expected: The dispatchChangeEvent property is added to the Array page.
This appears to be an issue related to Windows filenames. (I only use Windows when I'm forced to!) But the displayed filename should not include the C:... bit. If you create a new ticket in the issue tracker, I'll fire up my Windows emulator.
Michael Mathews
--- Running JsDoc on Win7 ---
Creating documentation with the standard template gives me an information of the source file. I have identified this in the template as meta.filename (is this correct?).
Is it possible to change it to just the filename, or the path starting with a given root directory. Is there a meta property for something like this.
Is:
C:...............\MyProject\js\MyClass.js
Wanted:
MyClass.js or MyProject\js\Myclass.js
Or is this just a way to leave a multiline comment that will automatically be ignored? Wasn't sure if this was a conscious design point.
It would be really neat if the exception type could be specified within the @throws tag.
For example,
/**
* Do something...
* @param {string} a
* @throws {MyError} when parameter was invalid.
*/
function foo(a) {
if (typeof a !== 'string')
throw new MyError('String was expected for parameter 1', 'invalid_param');
//...
}
Even the following would work, but the link seems to be ignored when at start of tag.
/** @throws {@link MyError} when parameter was invalid **/
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.