documentationjs / documentation Goto Github PK
View Code? Open in Web Editor NEW:book: documentation for modern JavaScript
Home Page: http://documentation.js.org/
License: Other
:book: documentation for modern JavaScript
Home Page: http://documentation.js.org/
License: Other
I don't think we should try to implement serverless search, but rather have templates by default have swiftype markup and a toggle-able swiftype option.
It's possible to infer parameters names from code. I'm not sure if this is a useful feature, though, since it opens a door to developer laziness.
This is sometimes useful: should we extract and embed code alongside the actual doc output, or provide links to GitHub or?
With the merged context
branch we now have loc
data and code snippets in docs. We can link to github in a transformer given a base path.
This should at least be an option.
JSDoc has a tutorials system as a sort of sidecar to docs.
This one cuts both ways:
Examples:
Requirements?
This project should be heavily documented, inside and out. Every single function should be documented.
Currently blocked by lack of parser support: http://esprima.org/doc/es6.html
Running list of things to support:
Switch to espree
JSDocs in destructuring assignment:
{ /** docs */ a, /** docs */ b } = { ... }
We should support pretty / beautiful HTML output as the default HTML output.
If possible, this would be a great way to separate concerns. We'd have the main parser attach an AST subtree to each comment, and could have separate stream transforms to do not only name inference but other context-sensitive things like memberof inference.
For instance
/**
* This function returns the number one.
* @return {Number} numberone
*/
function returnOne() {
// this returns 1
return 1;
}
Should infer a @name returnOne
tag.
Upstream of Turfjs/turf-www#78
Transform
/**
* this does foo
* @returns {number} foo
*/
module.exports = function() { return 42; };
Into
module.exports = function() { return 42; };
Object.defineProperty(module.exports, '__documentation__', {
enumerable: false,
value: {
// parsed comment
tags: []
description: 'this does foo'
}
});
And then traverse object hierarchy of module.exports to correctly name everything.
May be a terrible idea. /cc @jfirebaugh
Like name inference, but for @memberof
.
We don't want to document the dependencies of projects we document
This list is not comprehensive https://github.com/documentationjs/documentation/blob/master/streams/output/html.js#L27-80
Need this behavior, but does it need to be an option? Can it be the default?
all @yhahn
Akin to .jshintrc
or such, we could support declarative configuration - or we could support a more like docfile.js
convention and recommend everyone use the JS API
Space should not be used in array indices. array[ 0 ]
looks silly.
@mourner is a big fan of this and I have to agree: it's a very succinct way of showing all member functions of a class.
Right now lends is missing stuff like the addTo
method on the Popup control of Mapbox GL.
JSDoc's markdown plugin is pretty essential and we've heavily used it.
good parsers:
While sqlite3 has the beezneez of native module packaging, it's still a native module and still makes documentationjs installation more uncertain than it should be.
/**
* @param {number} a foo
*/
function bar() {
}
Should infer a kind: function
tag out of the fact that it's attached to a function
Documentation for OO libraries is typically organized like:
# Module
## Class
### Static methods
### Instance methods
### Events
There should be a transform that can group comments into a hierarchy like that, so that it's easy to flow them into a template.
✔︎: full support
➖: partial support
✘: no support
Complete
Tag | Core | Markdown | HTML | Issues |
---|---|---|---|---|
@alias |
✔︎ | ✔︎ | ✔︎ | |
@async |
➖ | ➖ | ➖ | |
@augments |
✔︎ | ✔︎ | ✔︎ | |
@deprecated |
✔︎︎ | ✔︎︎︎︎ | ✔︎︎︎︎ | |
@description |
✔︎︎ | ✔︎ | ✔︎ | |
@copyright |
✔︎︎ | ✔︎ | ✔︎ | |
@example |
✔︎︎︎︎ | ✔︎︎︎︎ | ✔︎︎︎︎ | |
@author |
✔︎ | ✔︎ | ✔︎ | |
@function |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@global |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@ignore |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@instance |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@lends |
✔︎︎︎︎ | ✔︎︎ | ✔︎︎ | lends is an inference hint |
@license |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@name |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@param |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@throws |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@member |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@version |
✔︎ | ✔︎ | ✔︎ | |
@returns |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@since |
✔︎ | ✔︎ | ✔︎ | |
@static |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@property |
✔︎︎︎︎ | ✔︎ | ✔︎ |
Unfinished
Tag | Core | Markdown | HTML | Issues |
---|---|---|---|---|
@abstract |
✔︎ | ✘ | ✘ | |
@access |
✔︎ | ➖ | ➖ | |
@borrows |
✘︎ | ✘ | ✘ | |
@inner |
✔︎︎︎︎ | ✔︎ | ✔︎ | |
@callback |
✔︎︎ | ✘ | ✘ | |
@class |
✔︎︎ | ✘ | ✘ | |
@classdesc |
✔︎︎ | ✘ | ✘ | #109 |
@constant |
✔︎︎ | ✘ | ✘ | |
@constructs |
✘︎︎ | ✘ | ✘ | |
@default |
✘︎︎ | ✘ | ✘ | |
@enum |
✘︎︎ | ✘ | ✘ | |
@event |
➖ | ✘ | ✘ | #96 |
@exports |
✘︎︎ | ✘ | ✘ | |
@external |
✔︎︎︎︎ | ✘ | ✘ | |
@file |
✔︎︎︎︎ | ✘ | ✘ | |
@fires |
✘︎︎︎︎ | ✘ | ✘ | |
@implements |
✘︎︎︎︎ | ✘ | ✘ | |
@inheritdoc |
✘︎︎︎︎ | ✘ | ✘ | |
@interface |
✔︎︎︎︎ | ✘ | ✘ | |
@kind |
✔︎︎︎︎ | ✘ | ✘ | |
@listens |
✘︎︎︎︎ | ✘ | ✘ | |
@memberof |
➖ | ✔︎ | ✔︎ | #189 |
@mixes |
✘︎︎︎︎ | ✘ | ✘ | |
@mixin |
✔︎︎︎︎ | ✘ | ✘ | |
@module |
✔︎︎︎︎ | ✘ | ✘ | |
@namespace |
✔︎︎︎︎ | ✘ | ✘ | |
@override |
✔︎︎︎︎ | ✘ | ✘ | |
@private |
✔︎ | ➖ | ➖ | |
@protected |
✔︎ | ➖ | ➖ | |
@public |
✔︎ | ➖ | ➖ | |
@readonly |
✔︎ | ✘ | ✘ | |
@requires |
✘︎︎︎︎ | ✘ | ✘ | |
@see |
✔︎ | ✘ | ✘ | |
@summary |
✔︎ | ✘ | ✘ | #341 |
@this |
✘︎︎︎︎ | ✘ | ✘ | |
@todo |
✔︎ | ✘ | ✘ | |
@tutorial |
✘︎︎︎︎ | ✘ | ✘ | |
@type |
✔︎ | ✘ | ✘ | |
@typedef |
✔︎ | ✘ | ✘ | #372 |
@variation |
✔︎ | ✘ | ✘ |
We should support babel and coffeescript to cast the net as wide as possible.
Should be able to maintain 100% code coverage for this module fairly easily.
We know of a few JSDoc oddities with no clear solution. Let's keep track of them here.
Need to implement {@link}
http://usejsdoc.org/tags-inline-link.html
{@link foo|bar}
Trying to run documentation
on documentation's own index.js
:
$ documentation index.js
events.js:72
throw er; // Unhandled 'error' event
^
Error: Cannot find module 'index.js' from '/Users/john/Development/documentation'
at /usr/local/lib/node_modules/documentation/node_modules/module-deps/node_modules/resolve/lib/async.js:46:17
at process (/usr/local/lib/node_modules/documentation/node_modules/module-deps/node_modules/resolve/lib/async.js:173:43)
at ondir (/usr/local/lib/node_modules/documentation/node_modules/module-deps/node_modules/resolve/lib/async.js:188:17)
at load (/usr/local/lib/node_modules/documentation/node_modules/module-deps/node_modules/resolve/lib/async.js:69:43)
at onex (/usr/local/lib/node_modules/documentation/node_modules/module-deps/node_modules/resolve/lib/async.js:92:31)
at /usr/local/lib/node_modules/documentation/node_modules/module-deps/node_modules/resolve/lib/async.js:22:47
at Object.oncomplete (fs.js:107:15)
documentation ./index.js
produces more interesting results. But unlike require
, relative paths not prefixed with ./
should be supported here.
If I @returns {boolean}
I get a nice link to the documentation for booleans.
However, if I @returns {BigInteger}
I don't get a link because documentation
doesn't know what it is (though it might be able to infer it by seeing that there's a BigInteger variable that's require
d from a node module and use the homepage from its package.json
for the URL)...
This would be something similar to doxme: README-friendly GFM output.
What order should documentation be displayed in? Right now the order is non-deterministic.
for usecases like documentation src/*.js
The output that pivot generates is still cumbersome to work with. It would be better to be opinionated about what tags are expected to be singular, and use a non-array value for them. Also, a lot of unnecessary structure should be collapsed.
E.g. instead of:
{
tags: {
name: [{title: "name", name: "Foo"}]
}
}
It should just be:
{
name: "Foo"
}
Look to the output of jsdoc -X
for guidance.
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.