GithubHelp home page GithubHelp logo

flow-jsdoc's People

Contributors

albe avatar kegsay avatar mabedan avatar stonecypher avatar wardpeet avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

dictav dannysu wardpeet stonecypher albe happy-ferret zmarouf simontegg mabedan okeeffed imsamurai

flow-jsdoc's Issues

Handling JSDoc comments generation from flow syntax

Hi !

Currently the project is generating flow syntas from jsdoc but do you think it would be able to go the other way around ?

From the following code :

function foo(bar: Array<Foobar>, baz: Function) : number {
    return 42;
}

Generate the JSDoc comment 👍

/**
 * @param {Foobar[]} bar
 * @param {Function} baz
 * @return {number}
 */
function foo(bar: Array<Foobar>, baz: Function) : number {
    return 42;
}

Regards,

Esprima can't parse codes which already have flow type annotations

Problem

Esprima can't parse codes which already have flow type annotations.

When we have foo.js like this:

// @flow

/**
 * @param {string} str
 */
function foo(str): string {
  return str;
}

... then flow-jsdoc dies, because esprima.parse() can't parse flow type annotation and throws a parse error.

$ flow-jsdoc -f foo.js

/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:552
	        throw this.unexpectedTokenError(token, message);
	        ^
Error: Line 6: Unexpected token :
    at ErrorHandler.constructError (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:3396:22)
    at ErrorHandler.createError (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:3414:27)
    at JSXParser.Parser.unexpectedTokenError (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:542:39)
    at JSXParser.Parser.throwUnexpectedToken (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:552:21)
    at JSXParser.Parser.expect (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:716:19)
    at JSXParser.Parser.parseFunctionSourceElements (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:2572:15)
    at JSXParser.Parser.parseFunctionDeclaration (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:2713:26)
    at JSXParser.Parser.parseStatementListItem (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:1809:39)
    at JSXParser.Parser.parseProgram (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:3061:29)
    at parse (/Users/fand/.nodenv/versions/6.9.5/lib/node_modules/flow-jsdoc/node_modules/esprima/dist/esprima.js:117:24)

It would be great if flow-jsdoc could parse such codes.
Replacing Esprima with Babylon will solve the problem.

Also, It would be nice if flow-jsdoc could handle the confliction between JSDoc types and existing flow type annotations 😺

Add more comments to functions

Would you mind splitting up the index.js in some smaller files and make the code a bit more manageable?

  • Like introducing "constants" instead of strings.
  • Splitting files

RangeError: Maximum call stack size exceeded

When I run the following command on a fresh checkout of nodecg/nodecg:

flow-jsdoc -d ./lib -o ./annotated

I receive the following error output:

C:\Users\vanca\Documents\Programming\nodecg\0.8>flow-jsdoc -d ./lib -o ./annotated
C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:90
                    throw err0;
                    ^

RangeError: Maximum call stack size exceeded
    at Object.fs.mkdirSync (fs.js:922:18)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:71:13)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:77:24)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)
    at sync (C:\Users\vanca\AppData\Roaming\npm\node_modules\flow-jsdoc\node_modules\mkdirp\index.js:78:17)

It seems to make the annotated folder then encounter this error.

Let me know if there's any further testing you'd like me to do to try to narrow down the problem.

Crash when a comment is included

The following code causes a crash:

function a() {
  return '';   // a
}

export { 
  a
};

Where as if you remove the // a comment it does not.

The crash error is:

/home/user/node_modules/flow-jsdoc/index.js:210
            if (declaration.type === 'VariableDeclaration') {
                            ^

TypeError: Cannot read property 'type' of null
    at getCommentedFunctionNode (/home/user/node_modules/flow-jsdoc/index.js:210:29)
    at decorateFunctions (/home/user/node_modules/flow-jsdoc/index.js:291:20)
    at /home/user/node_modules/flow-jsdoc/index.js:408:9
    at walk (/home/user/node_modules/flow-jsdoc/lib/falafel.js:62:9)
    at /home/user/node_modules/flow-jsdoc/lib/falafel.js:53:25
    at Array.forEach (<anonymous>)
    at forEach (/home/user/node_modules/flow-jsdoc/lib/falafel.js:10:31)
    at /home/user/node_modules/flow-jsdoc/lib/falafel.js:51:17
    at Array.forEach (<anonymous>)
    at forEach (/home/user/node_modules/flow-jsdoc/lib/falafel.js:10:31)

JSX support?

Hi!

When running the tool on a React-powered codebase, I get the (predictable) following error:

/media/neemzy/storage/aecf/gui • node_modules/.bin/flow-jsdoc -d ./app/Resources/scripts/ -o ./annotated

/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:5702
            throw e;
            ^
Error: Line 1481: Unexpected token <
    at constructError (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:2407:21)
    at createError (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:2426:17)
    at unexpectedTokenError (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:2500:13)
    at throwUnexpectedToken (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:2505:15)
    at parsePrimaryExpression (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:3307:13)
    at inheritCoverGrammar (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:2681:18)
    at parseLeftHandSideExpressionAllowCall (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:3414:20)
    at inheritCoverGrammar (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:2681:18)
    at parsePostfixExpression (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:3490:16)
    at parseUnaryExpression (/media/neemzy/storage/aecf/gui/node_modules/flow-jsdoc/node_modules/esprima/esprima.js:3550:20)

I'm unfamiliar with Esprima and code parsing in general; is there any way to make the parsing JSX-friendly in order to avoid this?

Thanks!

Optional parameters

Hey, first thanks for making this, this looks really cool. When trying this out I was realising that optional parameters don't seem to work. For example

// Input

/*
 * @param {string} [optional=world] 
 * @return {string}
 */
myClassFunction (greeter) {
  if (greeter) return 'hello ' + greeter
  return 'hello world'
}

will not be transformed at all.

Support for @static

Currently when using static properties for classes there is no way to make flow like them. Ideally a similar transform as is done for @prop would be done for @static.

Object spread

Seems that object spread doesn't work when converting.

// Doesn't work
return fetch(url, {
    ...opts,
    headers,
})

// Works
return fetch(url, Object.assign({}, opts, {
    headers,
}))
/XXX/node_modules/flow-jsdoc/app.js:84
                    throw err;
                    ^
Error: Line 33: Unexpected token ...
    at ErrorHandler.constructError (/XXX/node_modules/esprima/dist/esprima.js:3386:22)
    at ErrorHandler.createError (/XXX/node_modules/esprima/dist/esprima.js:3404:27)
    at JSXParser.Parser.unexpectedTokenError (/XXX/node_modules/esprima/dist/esprima.js:541:39)
    at JSXParser.Parser.throwUnexpectedToken (/XXX/node_modules/esprima/dist/esprima.js:551:21)
    at JSXParser.Parser.parseObjectPropertyKey (/XXX/node_modules/esprima/dist/esprima.js:1034:27)
    at JSXParser.Parser.parseObjectProperty (/XXX/node_modules/esprima/dist/esprima.js:1074:25)
    at JSXParser.Parser.parseObjectInitializer (/XXX/node_modules/esprima/dist/esprima.js:1140:35)
    at JSXParser.Parser.inheritCoverGrammar (/XXX/node_modules/esprima/dist/esprima.js:832:37)
    at JSXParser.Parser.parsePrimaryExpression (/XXX/node_modules/esprima/dist/esprima.js:904:38)
    at JSXParser.parsePrimaryExpression (/XXX/node_modules/esprima/dist/esprima.js:5355:97)
error Command failed with exit code 1.

ES6 default params

Doesn't add annotations to functions with default values.

// Works
/**
 * @param {string} url
 * @param {Object} opts
*/
const ajax = (url, opts) => {}


// Doesn't Work
/**
 * @param {string} url
 * @param {Object} opts
*/
const ajax = (url, opts = {}) => {}
 19: const ajax = (url: string, opts = {}) => {
                                ^^^^ parameter `opts`. Missing annotation

How integrate this into eslint

Hallo,
I think this is a great project. What I miss is a way to integrate it into eslint. I know that I can compile it manually and then pass it to the eslinter. This would work great for continuous integration tools, but what is about IDE'S like atom? Any idea how make existing plug ins for eslint work with this tool?

thanks for your time :)

Integration with Webpack/Babel

Hello,
thanks very much for your efforts!
I'm wondering how to integrate this into a webpack/babel project?

When in developing mode for a webpack project I'm not particularly interested into getting the compiled js (with flow types) but:
ES6+JsDoc with Flow Type Annotation -> ES5 + Flow (standard annotations) -> ES5 (without flow)

Any idea how to integrate this?

@typedef support?

I know it's in the future enhancement section, but is this still being planned? If not, I may fork and try to add it in myself. I really like this idea as a project of mine already uses JSDoc, and I want to add flow to it, but would rather not muck up the code if I don't have to. But I require @typedef support. Please let me know if there's any plan. Thanks.

Add support for constructor with default parameter

Constructor with default parameter does not gets converted:

  /**
   * TEXT
   * @param {string} key - TEXT
   * @property {string} key - TEXT
   * @constructor
   */
  constructor(key = 'VALUE') {
    this.key = key;
  }

If I remove the default value "= 'VALUE'") it's okay..

Doesn't seem to support ES6 fat arrow functions

for instance:

const obj = {
    /**
     * @function
     * @param {string} a
     * @param {string} b
     * @return {number}
     */
    func: (a, b) => {
        return 1;
    },
};

or

functionWithCallback(
/**
 * @function
 * @param {string} a
 * @param {string} b
 * @return {number}
 */
(a, b) => {
    return 1;
}
);

npm package has DOS line endings

As the issue title states, the published package has DOS line endings (\r\n instead of \n), which causes attempts to run on Unix-like systems to fail with the following error:

/usr/bin/env: ‘node\r’: No such file or directory

Tools like dos2unix may be of use here.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.