googlearchive / core-doc-viewer

Polymer element documentation viewer

core-doc-viewer

This element is compatible with Polymer 0.5 and lower only, and will be deprecated.
You can check out a similar 0.8-compatible version of this element at https://github.com/polymerelements/iron-doc-viewer

Note If you update elements in this repo, you'll need to rebuild build.sh in core-component-page-dev so they're used in the compiled version (core-component-page).

core-doc-viewer's Issues

/deep/ combinator is deprecated.

Hello Guys,
using a fresh install of Polymer WebStarter Kit, i get this error with the example provide :

/deep/ combinator is deprecated. See https://www.chromestatus.com/features/6750456638341120 for more details.

Someone says that's because shadow Piercing is being removed from the spec and thus Chrome deprecated it. However Polymer still uses it in some places (for example in iron-flex-layout).

core-doc-viewer still uses core-layout

Here's where I foudn:

https://github.com/Polymer/core-doc-viewer/blob/master/core-doc-viewer.html#L32
https://github.com/Polymer/core-doc-viewer/blob/master/elements/core-doc-page.html#L1
https://github.com/Polymer/core-doc-viewer/blob/master/elements/core-doc-toc.html#L1

@return annotations don't generate any docs

From @enguyen on October 17, 2014 19:16

See, e.g. the @return statement in sayHello's comment block -- no corresponding text in the generated doc.

In general, it would be great to have clearer documentation around which JSDoc annotations are supported, and if there are any restrictions (e.g. @param annotations may not be multiple lines.)

Copied from original issue: googlearchive/seed-element#36

Method parameter types look odd

The formatting at https://github.com/Polymer/core-doc-viewer/blob/0.4.1/elements/core-doc-page.html#L135 makes the documentation for method parameter types look a bit strange. As you can see in this screenshot, <code>( {{type}} )</code> kind of looks like the parameter name is a function, and the parameter type is a parameter (with spaces around the parenthesis).

I'd argue that something like

<p><code>&lt;<em>{{type}}</em>&gt; {{name}}</code></p>

would look better. If there's agreement, I can put together a PR for that change.

Add different sorting options

I think right now if you use sources it sorts everything alphabetically in the sidebar. But when I'm making a repo that has 3 related elements, I might want to appear in the order I entered them into the array.

For example, a collection of Twitter Bootstrap grid elements might look like this in index.html:

<core-component-page sources="[
    'twbs-grid.html',
    'bs-container.html',
    'bs-row.html',
    'bs-col.html'
  ]">
  </core-component-page>

It'd be cool if they could appear in that same order in the sidebar.

Support rendering `@property`s for an event

Including @param/@property for the event should render in the documentation:

<!--
Fired when the spreadsheet's cell information is available.

@event google-sheet-data
@param {Object} detail
@param {Object} detail.data Blah blah
@param {string} detail.type Blah blah
-->

Renders:

Methods should render their params

Including a @param with the method doc string doesn't end up in the rendered component page.

Doc viewer needs to be responsive (single and multi-column)

When viewed on googlewebcomponents.github.io, it needs to be responsive.

Only show `core-doc-toc` if component page has more than one element

Otherwise, there's a lot of wasted space. It's also confusing to have a one item list.

vs

Update to use new core-layout attributes

Instead of the css here:
0957394

Comments that wrap break parser

For example, the position param wraps for <=80 chars:

/**
  * Fired when the Geolocation API returns a position result.
  *
  * @param {Position} position The raw position object returned by
  *                   the Geolocation API.
  *

but produces:

core-docs no longer render because of css changes to core-layout/core-header-panel

I'd file this on core-docs, but that's mainly a shell repo.

Looks like changes to core-layout/core-header-panel CSS have caused this. Removing the following like from core-header-panel.css at least displays something:

:host {
  display: block;
  position: relative;
}

There's more afoot though. The layout has lost all of its flexboxiness (elements are reporting 0 height):

@frankiefu any quick fixes?

@param and @return doesn't support markdown

Parameters and return description (pending PR #36 ) are rendered in a span element instead of in a <marked-element>.

I understand a parameter description must be quite short (like no code sample) but it would be nice to be allowed to use value, word, word and links.

For instance :

@param {String} state Can be `success`, `alert` or `error`.

[0.8] Demo link or tab for the docs

move the toolbar from component-page to doc-viewer

The toolbar in core-component-page is nice, could we move it to to the core-doc-page, so every component of the doc gets it ? The bar is handy to add a demo link and source code link that will be always accessible even when looking informations at the bottom of a long scrolling page

It looks like it has been considered once here

Note: That will probably implies to removed the one existing from core-component-page

The @extend property can't link between elements categories

The doc viewer breaks @extend links for paper elements which extend core elements, since the hashtag is hardcoded in the href attribute of the link (see core-docs-page.html#L51).
An example of that issue would be the paper-tabs element's extend link.

My idea was maybe you can add something like an @extendPrefix property binding before the hashtag in order to allow linking to other categories as well (see this commit).
One could then use @extendPrefix /docs/elements/core-elements.html on elements which need it while the others would not need to be modified.

Thanks for the amazing work on Polymer guys, love it 👍

Support `@property`

For properties which are not published as attributes, we should support @property pragmas in the parser

Pressing Collapse, then Expand, then Show Private API, blank rows are rendered

@type only detected when after @attribute

For an element attribute's comment block, an @type annotation that appears before an @Attribute annotation is ignored (i.e. no type information appears in the generated doc viewer.) Moving the @type annotation below @Attribute allows the type information to appear.

Allow description to be separated from code examples

An @example pragma would make it easy to split your description from your code example. This is really helpful for writing docs where the code example needs to be styled differently from the description. The only way I've found to work around this is to add HTML to your markdown.

<!--
/**
 * @element patt-lead
 *
 * <span class="doc-description">Description:</span> Content preceding the
 * main body of a page or article.
 *
 * <p class="doc-usage">Usage:</p>
 * 
 *     <patt-lead>
 *       Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
 *       eiusmod tempor incididunt ut labore et dolore magna aliqua. Excepteur
 *       sint occaecat cupidatat non proident, sunt in culpa qui officia
 *       deserunt mollit anim id est laborum.
 *     </patt-lead>
 */
-->

Support @required

For required attributes/properties that need to be set to make the element function

Move searchBar work to a branch

While we're still developing the searchBar, could we move these elements, and the code that drives them in the element's prototype, over to a separate branch?

Support @extends

Many of our elements inherit from another. Folks need to navigate to the extendee's documents to learn about additional properties, methods, and api surface.

The doc-viewer can probably scrape the extends="" attribute.

core-doc-viewer should display @example as examples

It should be possible to include live demos in the docs like:

/**
@element my-element
@example <my-element>Content!</my-element>
*/

or

/**
@element my-element
@example example1.html
@example example2.html
*/

see http://getbootstrap.com/2.3.2/components.html
and http://semantic-ui.com/elements/button.html

Support @default

To users can know what the default value is. This seems to be in the context-free code by not surfaced in the UI.

@typdef / type definitions show us as "properties" in index.html

Created a typedef to describe a custom object used to return information from a function:

      /**
       @typedef MatchInfo
       @type {Object}
       @property {Boolean} matches If there is a match.
       @property {string} pre String before the match.
       @property {string} matching String matching from text.
       @property {string} post String after the matched text.
       */

The parser skips the @typedef and @type headers but publishes the listed properties in a weird "Properties" section:

[0.8] Private properties should be hidden by default

No way to not include a homepage

If no @homepage pragma is provided, the core-doc-page will use '//polymer.github.io/' + data.name.

Ok I understand that:

1. This is handy for you guys because it allow to omit this line
2. Providing a landing page is a good practice,

but if for some reasons we don't have a landing page or don't want to expose it, we're stuck with that link and icon.

Would you accept a PR that does the following ?

• If no @homepage pragma supplied then the icon and link is hidden
• If @homepage github.io then use '//polymer.github.io/' + data.name

(The last bullet allows you to not go through most of your repo and modify the pragma)

Support `@github` in core-doc-page

core-doc-page doesn't make it easy to get back to the code on Github:

It should render a link back to Github.

can 'http' cause difficulties with https environments like firebaseapp webhosting

I found "href='http://fonts.googleapis.com/" in core-doc-page.html.

Add a description in the GitHub repository

How do you use this?

Can't find any documentation on how you use this

core-doc-page should render it's own demo button

Otherwise, the core-docs for example, just includes one demo button that 404s: