3.0 API doc: possible improvements

[arthurevans]

Current file overview is a little confusing. Especially weird to have the tiny import line be the first thing on the page, followed by a giant headline for the element/class. This might look better once the @fileoverview tag is implemented.

Current format doesn't seem to document symbols that are re-exported. For example, the polymer-element Module page doesn't show the html function.

My first thought was that it was weird to have the element/class embedded directly in the module page , but I guess the vast majority of our modules only export one thing. The challenge here is that if a single module exported two elements, or an element and some functions, it would be virtually impossible to figure out that the other items were there unless you knew to look for them.

I think this issue could be addressed with a quick-reference at the beginning of the file, so you have something like:

File overview description

import {} from '@polymer/polymer/polymer-element.js'

Exports: PolymerElement, html, fooBar

Where each item in the Exports list is a link to the corresponding item.

But this might look weird if almost all of our files have only a single export.

A TOC or some other navigation aid would serve the same purpose of orienting people in the file (in fact, it'd be even better for large elements/mixins with lots of props and methods). Maybe we can get someone with a design-y eye to look at it.

As far as the URLs go, the current URL fragments assume that each module is only exporting a single class/element. For example, if you had a single module that exported simple-dialog and fancy-dialog, each with an open method, the fragments for both would look identical:

my-dialogs#method-open

Not sure if I am borrowing trouble here. But I'd hate to rewrite all of the links to the API docs and then change the URLs, so let's discuss this assumption.

[rictic]

This is really great feedback. I filed some sub-issues to track resolving these point.

[arthurevans]

One example in the actual docs:

The mutable-data module exports two mixins, MutableData and OptionalMutableData, but you can't link directly to the mixins (issue #1) and if you get linked to the module, it's not immediately apparent that the second mixin is in there (so you might just think it's a bad link) (issue #2). It sounds like issue #2 is covered under PolymerElements/iron-doc-viewer#178, but it's not clear to me whether issue #1 is covered under that issue or not (in either case, we need a way to link to the individual thingies under a module, like mixins or elements.