docs/api.md should be linted about puppeteer HOT 3 CLOSED

Others on my team put together: https://googlechrome.github.io/npm-publish-scripts/travis-to-github-pages.html#main. Example api page that uses it: https://googlechrome.github.io/sw-toolbox/api.html#main

I've never used it myself. Looks like the md files are still manually maintained: https://github.com/GoogleChrome/sw-toolbox/tree/master/docs

from puppeteer.

With the latest change, it's not scary any more to edit api.md manually. So there's no point in generating it any more.

However, the doc is getting outdated pretty fast. So the issue should be about linting api.md and making sure it is up-to-date (at least to some extend).

from puppeteer.

Now there's a doclint utility which lints codebase against markdown's api.md documentation. doclint is a part of npm run lint command. It could be also run separately via the npm run doc command.

The utility makes sure that the following entities in documentation are aligned with codebase:

• classes
• methods, method arguments and method return statements
• public properties, such as browser.stderr
• events, such as Page's 'dialog' event
• proper sorting of class members (events first, then constructor, then all the other members)

doclint doesn't generate any markup, it instead complains when it finds a mismatch.
doclint messages might be confusing at times and there should be some bugs - feel free to complain. We'll smooth it out over time.

I think this implements all the necessary features for the documentation linting.

from puppeteer.