docs(api): generate API docs from source

[manekinekko]

FIX #2463

The generated documentation looks like this:

You can generate the api doc using the npm command: npm run generate-docs

I set the output folder in docs/api (this is configurable in .jsdoc.json)

However, it seems that some jsdocs comments are valid like this:

ERROR: Unable to parse a tag's type expression for source file 
lighthouse/lighthouse-core/gather/gatherers/dobetterweb/optimized-images.js in line 181 with tag title "return" and text "{!Promise<!Array<!Object>}": Invalid type expression "!Promise<!Array<!Object>": Expected ",", "=", ">" or "|" but end of input found.

TBH, I'm not familiar with this syntax. any idea how to fix this?

[patrickhulce]

WOW thanks @manekinekko!! the error you're getting is from some of our invalid closure types, just missing a > :)

[paulirish]

I just staged this up on my gh-pages: http://paulirish.github.io/lighthouse/docs/api/lighthouse/2.5.1/

[paulirish]

Thanks very much for doing this.

After some discussion we're not going to include this. Some of our recent typing work will definitely assist with the goals of #2463

Cheers!

[manekinekko]

Sounds good 👍