Update documentation

Author: runem

ANALYZE.md

@@ -2,7 +2,7 @@
 
 # Overview of what this library can analyze
 
-This library is designed to analyze components no matter where they are found. This means it needs to find and analyze components in both javascript, typescript and in typescript definition (when consumed from a library).
+This library is designed to analyze components no matter where they are found. This means it needs to find and analyze components in both javascript, typescript and in typescript definition files (when consumed from a library).
 
 As you can see we loose a lot of information when the element is defined in a typescript definition file.
 
@@ -27,9 +27,9 @@ export class MyElement extends HTMLElement {
 customElements.define("my-element", MyElement);
 ```
 
--   **Tag name**: `my-element`
--   **Properties**: `value`, `myProp (String)`
--   **Attributes**: `attr1`, `attr2`
+- **Tag name**: `my-element`
+- **Properties**: `value`, `myProp (String)`
+- **Attributes**: `attr1`, `attr2`
 
 #### In typescript definition files
 
@@ -48,9 +48,9 @@ declare global {
 }
 ```
 
--   **Tag name**: `my-element`
--   **Properties**: `value (String)`, `myProp (String)`
--   **Attributes**: No attributes because `observedAttributes` is just a function that returns `string[]`
+- **Tag name**: `my-element`
+- **Properties**: `value (String)`, `myProp (String)`
+- **Attributes**: No attributes because `observedAttributes` is just a function that returns `string[]`
 
 ## [LitElement](https://lit-element.polymer-project.org/guide)
 
@@ -78,9 +78,9 @@ export class MyElement extends LitElement {
 }
 ```
 
--   **Tag name**: `my-element`
--   **Properties**: `myProp (String)`, `prop1 (String)`, `prop2 (Number)`, `prop3 (Boolean)`, `prop4 (String)`, `prop5 (Boolean)`
--   **Attributes**: `prop1 (String)`, `prop-two (Number)`, `prop4 (String)`, `prop-5 (Boolean)`,
+- **Tag name**: `my-element`
+- **Properties**: `myProp (String)`, `prop1 (String)`, `prop2 (Number)`, `prop3 (Boolean)`, `prop4 (String)`, `prop5 (Boolean)`
+- **Attributes**: `prop1 (String)`, `prop-two (Number)`, `prop4 (String)`, `prop-5 (Boolean)`,
 
 #### In typescript definition files
 
@@ -136,10 +136,10 @@ export class MyEmbeddedComponent {
 }
 ```
 
--   **Tag name**: `my-embedded-component`
--   **Properties**: `color (String)`
--   **Attributes**: `color (String)`
--   **Events**: `change`, `todoCompleted`
+- **Tag name**: `my-embedded-component`
+- **Properties**: `color (String)`
+- **Attributes**: `color (String)`
+- **Events**: `change`, `todoCompleted`
 
 ### In typescript definition files
 
@@ -179,28 +179,8 @@ declare global {
 }
 ```
 
--   **Tag name**: `progress-ring`
--   **Properties**: `decimalSize (Number)`
--   **Attributes**: `decimalSize (Number)`
+- **Tag name**: `progress-ring`
+- **Properties**: `decimalSize (Number)`
+- **Attributes**: `decimalSize (Number)`
 
-## [SkateJS](https://skatejs.netlify.com/)
-
-<h5 style="color: red">This is not supported yet.</h5>
-
-```javascript
-class MyElement extends Element {
-	static props = {
-		name: String
-	};
-}
-```
-
-```javascript
-class MyElement extends Element {
-	static get props() {
-		return {
-			todos: Array
-		};
-	}
-}
-```
+In addition, the entire content of HTMLElement is copied into the interfaces, so WCA makes sure to filter that out.

README.md

@@ -12,14 +12,13 @@
 
 </p>
 
-`web-component-analyzer` is a CLI that makes it possible to easily analyze web components. It analyzes your code and jsdoc in order to extract `properties`, `attributes`, `methods`, `events`, `slots` and `css custom properties`. Works with both javascript and typescript.
+`web-component-analyzer` is a CLI that makes it possible to easily analyze web components. It analyzes your code and jsdoc in order to extract `properties`, `attributes`, `methods`, `events`, `slots`, `css shadow parts` and `css custom properties`. Works with both javascript and typescript.
 
-In addition to [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) this tool supports web components built with the following libraries:
+In addition to [vanilla web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) this tool supports web components built with the following libraries:
 
 - [lit-element](https://github.com/Polymer/lit-element)
 - [polymer](https://github.com/Polymer/polymer)
 - [stencil](https://github.com/ionic-team/stencil) (partial)
-- [skatejs](https://github.com/skatejs/skatejs) (coming soon)
 - [open an issue for library requests](https://github.com/runem/web-component-analyzer/issues)
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#installation)
@@ -33,9 +32,7 @@ $ npm install -g web-component-analyzer
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#usage)
 
-## ➤ Usage
-
-### Analyze
+## Analyze
 
 The analyze command analyses an optional `input glob` and emits the output to the console as default. When the `input glob` is omitted it will find all components excluding `node_modules`. The default format is `markdown`.
 
@@ -46,36 +43,51 @@ The analyze command analyses an optional `input glob` and emits the output to th
 $ wca analyze
 $ wca analyze src --format markdown
 $ wca analyze "src/**/*.{js,ts}" --outDir components
-$ wca analyze my-element.js --outFile my-element.json
+$ wca analyze my-element.js --outFile custom-elements.json
 ```
 
-#### Options
+### Options
 
 | Option               | Type                             | Description                                                                  |
 | -------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
 | `--format FORMAT`    | `markdown` \| `json` \| `vscode` | Specify output format.                                                       |
 | `--outFile FILE`     | `file path`                      | Concatenate and emit output to a single file.                                |
 | `--outDir DIRECTORY` | `directory path`                 | Direct output to a directory where each file corresponds to a web component. |
 
-### Diagnose
+[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#api)
 
-The diagnose command analyses components and emits diagnostics. Right now it only emits diagnostics for LitElement's. When the optional `input glob` is omitted it analyzes all components excluding `node_modules`. If any diagnostics are emitted this command exits with a non zero exit code.
+## Output Formats
 
-<img src="https://user-images.githubusercontent.com/5372940/54445382-efeac700-4744-11e9-9a7b-92c5d251e124.gif" />
+### json
 
-<!-- prettier-ignore -->
 ```bash
-$ wca diagnose
-$ wca diagnose src
-$ wca diagnose "./src/**/*.{js,ts}"
-$ wca diagnose my-element.js
+wca analyze src --format json --outFile custom-elements.json
 ```
 
-[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#api)
+This json format is for experimental and demo purposes, and is still being actively discussed. You can expect changes to this format. Please follow and contribute to the discussion at:
+
+- https://github.com/webcomponents/custom-elements-json
+- https://github.com/w3c/webcomponents/issues/776
+
+### markdown
+
+```bash
+wca analyze src --format markdown --outDir readme
+```
+
+Web Component Analyzer can output markdown documentation of your web components. This can either be output into a single file using `--outFile` or into multiple files using `--outDir`.
+
+### vscode
+
+```bash
+wca analyze src --format vscode --outFile vscode-html-custom-data.json
+```
+
+VSCode supports a JSON format called [vscode custom data](https://github.com/microsoft/vscode-custom-data) for the built in html editor which is set using `html.customData` vscode setting. Web Component Analyzer can output this format.
 
 ## ➤ API
 
-You can also use the underlying functionality of this tool if you don't want to use the CLI. More documentation coming soon.
+You can also use the underlying functionality of this tool if you don't want to use the CLI. Documentation will be added as soon as the API is considered stable.
 
 <!-- prettier-ignore -->
 ```typescript
@@ -90,17 +102,17 @@ analyzeComponents(sourceFile, { checker });
 
 This tool extract information about your components by looking at your code directly and by looking at your JSDoc comments.
 
-**Code**: In addition to `custom elements` this tool supports `lit-element`, `stencil`, `polymer` and `skatejs` web components. [Click here](https://github.com/runem/web-component-analyzer/blob/master/ANALYZE.md) for an overview of how each web component type is analyzed.
+**Code**: Web Component Analyzer supports multiple libraries. [Click here](https://github.com/runem/web-component-analyzer/blob/master/ANALYZE.md) for an overview of how each library is analyzed.
 
 **JSDoc**: Read next section to learn more about how JSDoc is analyzed.
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#how-to-document-your-components-using-jsdoc)
 
 ## ➤ How to document your components using JSDoc
 
-In addition to analyzing properties on your components this library also use JSDoc to construct the documentation. It's especially a good idea to use JSDoc for documenting `slots`, `events` and `cssprops` as these are under no circumstances analyzed statically by this tool as of now.
+In addition to analyzing the code of your components, this library also use JSDoc to construct the documentation. It's especially a good idea to use JSDoc for documenting `slots`, `events`, `css custom properties` and `css shadow parts` as these not analyzed statically by this tool as of now (except when constructing a CustomEvent within your component).
 
-Here's an example including all supported JSDoc tags. All tags are on the the form `@tag {type} name - comment`.
+Here's an example including all supported JSDoc tags. All JSDoc tags are on the the form `@tag {type} name - comment`.
 
 <!-- prettier-ignore -->
 ```javascript
@@ -150,15 +162,15 @@ class MyElement extends HTMLElement {
 
 ### Overview of supported JSDoc tags
 
-| JSDoc Tag                    | Description                                                                                                                                             |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@element`                   | Gives your component a tag name. This JSDoc tag is especially useful if your 'customElements.define` is called dynamically eg. using a custom function. |
-| `@fires`                     | Documents events.                                                                                                                                       |
-| `@slot`                      | Documents slots. Using an empty name here documents the unnamed (default) slot.                                                                         |
-| `@attr` or `@attribute`      | Documents an attribute on your component.                                                                                                               |
-| `@prop` or `@property`       | Documents a property on your component.                                                                                                                 |
-| `@cssprop` or `@cssproperty` | Documents a css custom property on your component.                                                                                                      |
-| `@csspart`                   | Documents a css shadow part on your component.                                                                                                          |
+| JSDoc Tag                    | Description                                                                                                                                  |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@element`                   | Gives your component a tag name. This JSDoc tag is useful if your 'customElements.define` is called dynamically eg. using a custom function. |
+| `@fires`                     | Documents events.                                                                                                                            |
+| `@slot`                      | Documents slots. Using an empty name here documents the unnamed (default) slot.                                                              |
+| `@attr` or `@attribute`      | Documents an attribute on your component.                                                                                                    |
+| `@prop` or `@property`       | Documents a property on your component.                                                                                                      |
+| `@cssprop` or `@cssproperty` | Documents a css custom property on your component.                                                                                           |
+| `@csspart`                   | Documents a css shadow part on your component.                                                                                               |
 
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/colored.png)](#contributors)