Docs: Updated documenbtation for the element

raml-documentation-panel.html

@@ -21,30 +21,50 @@
 <link rel="import" href="../raml-docs-types-viewer/raml-docs-types-viewer.html">
 <link rel="import" href="raml-documentation-empty-state.html">
  <!--
-The documentation details panel.
-Is shows a documentation panel depending on if the selected object is a
-method, resource or the documentation node.
+The documentation viewer.
 
-The computation of the selected object should be performed outside the element.
-Use the `raml-path-selector` with `raml-path-to-object` to get the data
-structure that this element can work with.
+It displays a documentation panel depending on if the selected object is a
+method, resource, type or the documentation node.
+
+The element will compute current view from the `path` property. However, if
+the app is using [raml-path-to-object](https://elements.advancedrestclient.com/elements/raml-path-to-object)
+element the you can set the `handlePathEvents` property which will make the
+element to register event listeners fired from the `raml-path-to-object`
+element. It will skip internall path computation to not double the work.
+
+The element is consisted with the following documentation viewers:
+- raml-docs-method-viewer
+- raml-docs-resource-viewer
+- raml-docs-documentation-viewer
+- raml-summary-view
+- raml-docs-types-viewer
+
+Elements that are not displayed at a time are demoved from the DOM and are
+inavtive. Only active elements observe changes to the `selected-object` property
+and perform internall computation (it's optimisation).
 
 ### Example
-```
-<raml-path-to-object selected-object="{{obj}}" ...></raml-path-to-object>
-<raml-documentation-panel
-  selected-object="[[obj]]"
-  selected-parent="[[selectedParent]]"
-  path="[[path]]"></raml-documentation-panel>
-```
-or
-```
-document.querySelector('raml-documentation-panel').selectedObject = obj;
+```html
+<raml-path-to-object path="types.0"></raml-path-to-object>
+<raml-documentation-panel handle-path-events"></raml-documentation-panel>
+<script>
+var pto = document.querySelector('raml-path-to-object');
+var docs = document.querySelector('raml-documentation-panel');
+pto.addEventListener('selected-object-changed', function(e) {
+  docs.selectedObject = e.detail.value;
+});
+pto.addEventListener('selected-parent-changed', function(e) {
+  docs.selectedParent = e.detail.value;
+});
+</script>
 ```
 
-The `path` property is required because the `raml-docs-resource-viewer`
-required current path to compute relative paths to sub-resources.
+### Handling scrolling
 
+Set the `scrollTarget` to an element that has a scroll region to suppoer
+scrolling in the elements. The resource documentation panel handles internall
+links that are expected to scroll the view to correspoinding sections.
+This default to the window object.
 
 ### Styling
 `<raml-documentation-panel>` provides the following custom properties and mixins for styling: