gr0uch/doc-tree

Documentation generating tool for JavaScript that matches comments to AST nodes.

doc-tree's Issues

Purpose of Docchi?

If I understand correctly, Docchi exists to solve things like yui/yuidoc#336 correct?

Property assignments not providing context

This is basically a rehash of the previous issue with a new twist. I had to split up my file because docchi was not understanding classes as properties, like

Invoice.Item = class {
}

It would pick up the class, but not any methods or constructors in it. And when it did pick up things, the target was basically a dotted list of the other classes it had found in the file even though these were not inner classes. So I figured single entity per file was better anyways, but then my enums stopped working somehow:

/**
 * Valid invoice statuses
 * @enum {number}
 */
var InvoiceStatus = {
    /**
     * The invoice has not been saved to the server
     */
    NEW: 0
};

The second comment there gets picked up with no context and without the "NEW" information.

How do I use docchi once it generates the JSON?

Once docchi has generated its JSON, how can I turn that into HTML documentation?

You say that it's generated in a JSDoc format, but (as far as I can tell) JSDoc doesn't provide anything to read what docchi outputs.

Could you help me out? This might be a great thing to put in the README
Thanks

Not parsing inside methods?

I have the following:

/**
 * Container for addresses used on various invoice entities
 * @class
 */
Invoice.Address = class {
    constructor() {
        /**
         * @memberOf Invoice.Address
         * @member {string} line2
         */
    }
};

docchi parses the first comment but not the second. Any idea why?

Support files that use babel's experimental es7

I'm trying to use docchi to generate documentation for code that uses babel's experimental es7 syntax.
http://babeljs.io/docs/usage/experimental/

In my case I've got code that makes use of decorators. This is where it fails to parse:

Uncaught (in promise) SyntaxError: Unexpected character '@' (22:0)
    at Parser.8.pp.raise (http://localhost:3000/bundle/handbook.js:13493:15)
    at Parser.16.pp.getTokenFromCode (http://localhost:3000/bundle/handbook.js:15234:10)
    at Parser.16.pp.readToken (http://localhost:3000/bundle/handbook.js:14937:17)
    at Parser.16.pp.nextToken (http://localhost:3000/bundle/handbook.js:14929:73)
    at Parser.16.pp.next (http://localhost:3000/bundle/handbook.js:14878:10)
    at Parser.12.pp.eat (http://localhost:3000/bundle/handbook.js:13949:12)
    at Parser.12.pp.semicolon (http://localhost:3000/bundle/handbook.js:13991:15)
    at Parser.14.pp.parseVarStatement (http://localhost:3000/bundle/handbook.js:14386:10)
    at Parser.14.pp.parseStatement (http://localhost:3000/bundle/handbook.js:14185:21)
    at Parser.14.pp.parseTopLevel (http://localhost:3000/bundle/handbook.js:14127:23)
8.pp.raise @ acorn.js:1745
16.pp.getTokenFromCode @ acorn.js:3486
16.pp.readToken @ acorn.js:3189
16.pp.nextToken @ acorn.js:3181
16.pp.next @ acorn.js:3130
12.pp.eat @ acorn.js:2201
12.pp.semicolon @ acorn.js:2243
14.pp.parseVarStatement @ acorn.js:2638
14.pp.parseStatement @ acorn.js:2437
14.pp.parseTopLevel @ acorn.js:2379
parse @ acorn.js:101
Docchi @ index.js:72
parse @ index.js:160
(anonymous function) @ HomePage.js:50

Is this something you intend to support in the future?

What can I use to render the json file to HTML output?

2D Array Syntax Not Supported

I filed a similar issue with doctrine, but docchi doesn't seem to support 2D arrays either. JSDoc supports them and I've asked doctrine if they'll add support. It would be nice to have it here too because all my code is ES6.

Here's a valid docstring:

/**
 * @param {Number[]} test
 */

Here's an invalid docstring according to docchi:

/**
 * @param {Number[][]} test
 */

Rename package

google results turn up a yaoi manga so docchi is probably not the best name.

I did some googling around for "ast doc" and found this: https://github.com/jmoyers/ast-doc

which does exactly what this module does, though this is way more complete. fortunately the npm package ast-doc is not taken so maybe it's a good option.

Improve CLI

In retrospect using stdio is kind of silly because it can stream neither input nor output. This would be far simpler and allow for directory I/O:

docchi input.js -o output.json

Having a default usage text and --version would be nice.

Error: Cannot find module 'babel-runtime/helpers'

Trying to run Docchi on https://github.com/bevry/taskgroup es6 branch

$ npm i docchi
$ ./node_modules/.bin/docchi < es6/lib/taskgroup.js
module.js:318
    throw err;
          ^
Error: Cannot find module 'babel-runtime/helpers'
    at Function.Module._resolveFilename (module.js:316:15)
    at Function.Module._load (module.js:258:25)
    at Module.require (module.js:345:17)
    at require (module.js:364:17)
    at Object.<anonymous> (/Users/balupton/Projects/taskgroup/node_modules/docchi/dist/lib/cli.js:3:21)
    at Module._compile (module.js:410:26)
    at Object.Module._extensions..js (module.js:428:10)
    at Module.load (module.js:335:32)
    at Function.Module._load (module.js:290:12)
    at Module.require (module.js:345:17)

No `location` on output

I'm using docchi to parse some Jasmine test files to extract useful JSdoc tags to tie the tests back to their tickets.

I would like to receive the location of each comment block, which the documentation leads me to believe is already done, but I receive no output on location...

Output is:

[ { comment: { description: '<p>Before comment</p>\n', tags: [Object] } },
  { comment:
     { description: '<p>Describe block comment</p>\n',
       tags: [Object] } },
  { comment: { description: '', tags: [Object] } } ]

IS

Is there a way to include acorn plugins like https://github.com/RReverser/acorn-jsx. The way acorn is required makes that seem difficult.

Empty array as output

$ git clone https://github.com/bevry/taskgroup.git taskgroup
$ cd taskgroup
$ git checkout es6
$ npm i docchi
[email protected] node_modules/docchi
├── [email protected]
├── [email protected] ([email protected], [email protected])
├── [email protected] ([email protected])
└── [email protected]
$ ./node_modules/.bin/docchi < es6/lib/taskgroup.js
[]

File in question: https://github.com/bevry/taskgroup/blob/ce68612288191444c4d01ea31abbacea0c295fb8/es6/lib/taskgroup.js

Flow Type support?

Would be great to have built in support for http://flowtype.org somehow...

Full implementation of recursive walk.

Right now, Docchi can mostly parse only the top level of the AST because it's not using recursion in most places.