generate html API docs for artifacts, driver, etc

[brendankenny]

generated API docs could be very helpful, preventing the need to dive into multiple gatherers just to see what they provide in their artifacts, for instance. Ideally these would be generated from source with a single npm command.

• It may not be necessary (or even helpful) to have html docs for everything, but docs for key pieces would aid those developing Lighthouse core and/or their own extensions of it. Driver, the artifacts returned by all the core gatherers, and maybe things like the Audit and Gatherer base classes would be a great first start. OTOH, things like GatherRunner may not be helpful to many (but it does have that sweet execution outline)

• One issue is that the existing jsdoc declarations are a little spread out and not always complete. Driver is more or less documented in place, but the artifacts returned by gatherers often aren't, and instead you'd have to look to the closure externs for those types. Hopefully efforts to document all of this will help suggest how to better document the different parts of our architecture in a way that's maintainable and stays current.

• It's not clear how the docs should be laid out. It probably makes sense to do more of a logical grouping than one based on file location...e.g. you don't want to have to navigate to 20 different pages to see all the different artifact types, but Driver should probably be a page on its own. Again we want something maintainable, but also something that humans will be able to easily browse.

[brendankenny]

labelling this as a good first bug, especially for those with experience with the different documentation-generating tools out there.

If you do make an attempt at this, just generating a subset of the above (e.g. from just Driver or from just the Artifacts externs) would be a good first step. It would also allow evaluation of the format and a chance to figure out what would need to be done to bring everything else we need documented into an ingestible state without putting it all on the author :)

[stramel]

I definitely agree that Driver, Audit, and Gatherer were very useful to read into when I was first looking at developing a new Audit. I also found GatherRunner very informative. I'm interested to see what comes of this! 👍