documentationjs/documentation

:book: documentation for modern JavaScript

documentation's Issues

Whitelist dependency documentation

Upstream of Turfjs/turf-www#78

• through a cli argument, maybe a wildcard, permit documentation to document dependencies.

more opinionated pivot operation

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.

Infer parameters

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.

documentation bin should support simple relative paths

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.

Show or link code with docs

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.

memberof inference

Like name inference, but for @memberof.

Fix lends

Right now lends is missing stuff like the addTo method on the Popup control of Mapbox GL.

adjust space-in-brackets eslint setting

Space should not be used in array indices. array[ 0 ] looks silly.

HTML formatter doesn't correctly format 'undefined' output

infer @kind

Read & support project name in outputs

Search

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.

Expand range of builtsin

This list is not comprehensive https://github.com/documentationjs/documentation/blob/master/streams/output/html.js#L27-80

UI Wishlist

Methods Table

@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.

• Permalinks: Every atom of text should be permalinkable

Table of contents

Plain English vs API docs

Olark's implementation is very impressive

Docset output

http://kapeli.com/docsets

@lends support for memberof inference

http://usejsdoc.org/tags-lends.html

implement name inference as stream transform

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.

Differentiate with permalinks between variations of the same function

Maybe the permalinks should include the function signature

Support Markdown in descriptions

JSDoc's markdown plugin is pretty essential and we've heavily used it.

good parsers:

• https://github.com/jonschlinkert/remarkable
• https://github.com/chjj/marked

--lint

• "function named exports: do you want to name this function?"
• String where string was expected, object where Object was expected
• Unsupported tag detected: this shouldn't happen until we support way more tags
• Normalization detected

HTML Output

We should support pretty / beautiful HTML output as the default HTML output.

Template engine

• Could go whole-hog with something like consolidate.js, but I feel like supporting something simple like ejs or underscore templates would work.

Move docset generator out of core

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.

Mobile styles

• Hamburgler menu
• no resize meta tag

Add fixture outputs to tests

Markdown output

This would be something similar to doxme: README-friendly GFM output.

• Add configurable template option on bin level
• Helper function that formats type descriptions into Markdown
• Figure out when and where to run pivot

Documentation

This project should be heavily documented, inside and out. Every single function should be documented.

Documentation documentation

• How do I read documentation?
  • Explain difference between # and . for instance and static methods

Test documentation of get/set properties

skipSingleStar

Need this behavior, but does it need to be an option? Can it be the default?

transform to type hierarchy

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.

Documentation sorting order

What order should documentation be displayed in? Right now the order is non-deterministic.

Page-per-function style for HTML documentation

This should at least be an option.

Support multiple entry points?

for usecases like documentation src/*.js

Links for types from other modules

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 required from a node module and use the homepage from its package.json for the URL)...

Browserify transform mode

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

JSDoc shortcomings

We know of a few JSDoc oddities with no clear solution. Let's keep track of them here.

• Overloaded functions tmcw-up-for-adoption/doxme#10 (comment)

Website

Tag Support Master Ticket

✔︎: 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	✔︎	✘	✘

ES6 support

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 } = { ... }
  

don't output @private tags by default / add -p option

Infer kinds from AST

/**
 * @param {number} a foo
 */
function bar() {
}

Should infer a kind: function tag out of the fact that it's attached to a function

Transformers

We should support babel and coffeescript to cast the net as wide as possible.

• browserify transforms

Integration with narrative docs

JSDoc has a tutorials system as a sort of sidecar to docs.

This one cuts both ways:

• Narrative docs are a must-have alongside API docs
• There are many other systems that are great and geared towards narratives, like Jekyll and GitBook
• Linking to narrative docs and packaging them in a reasonable manner is a top priority

Examples:

• https://github.com/lxbarth/docfish

Requirements?

• translations?

Code coverage

Should be able to maintain 100% code coverage for this module fairly easily.

Document each field in output object

filter out module-deps in node_modules

We don't want to document the dependencies of projects we document

JSON configuration file

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

pixelz

all @yhahn

Infer function names from code

For instance

/**
 * This function returns the number one.
 * @return {Number} numberone
 */
function returnOne() {
  // this returns 1
  return 1;
}

Should infer a @name returnOne tag.

• What other names should we infer?
• What about function expressions?

inline tags

Need to implement {@link} http://usejsdoc.org/tags-inline-link.html

• Basic Markdown support
• Test with non-simple tags, like {@link foo|bar}
• HTML support