Update the plugin development documentation.

- link PolyGerrit plugin development guide from old one.
- There can only be one Gerrit.install() per file.
- fix phrasing, code samples.

Bug: Issue 7700
Change-Id: I9c65fed0d1e5831a3e8268a48bb729ad8a1af610

Documentation/dev-plugins.txt

@@ -3,6 +3,9 @@
 The Gerrit server functionality can be extended by installing plugins.
 This page describes how plugins for Gerrit can be developed.
 
+For PolyGerrit-specific plugin development, consult with
+link:pg-plugin-dev.html[PolyGerrit Plugin Development] guide.
+
 Depending on how tightly the extension code is coupled with the Gerrit
 server code, there is a distinction between `plugins` and `extensions`.
 

Documentation/pg-plugin-dev.txt

@@ -1,29 +1,38 @@
 = Gerrit Code Review - PolyGerrit Plugin Development
 
+CAUTION: Work in progress. Hard hat area. Please
+link:https://bugs.chromium.org/p/gerrit/issues/entry?template=PolyGerrit%20plugins[send
+feedback] if something's not right.
+
 [[loading]]
 == Plugin loading and initialization
 
-link:https://gerrit-review.googlesource.com/Documentation/js-api.html#_entry_point[Entry
-point] for the plugin and the loading method is based on
-link:http://w3c.github.io/webcomponents/spec/imports/[HTML Imports] spec.
+link:js-api.html#_entry_point[Entry point] for the plugin and the loading method
+is based on link:http://w3c.github.io/webcomponents/spec/imports/[HTML Imports]
+spec.
 
-* The plugin provides index.html, similar to
-  link:https://gerrit-review.googlesource.com/Documentation/dev-plugins.html#deployment[.js
-  Web UI plugins]
-* index.html contains a `dom-module` tag with a script that uses
-  `Gerrit.install()`.
-* PolyGerrit imports index.html along with all required resources defined in it
-  (fonts, styles, etc)
+* The plugin provides pluginname.html, and can be a standalone file or a static
+  asset in a jar as a link:dev-plugins.html#deployment[Web UI plugin].
+* pluginname.html contains a `dom-module` tag with a script that uses
+  `Gerrit.install()`. There should only be single `Gerrit.install()` per file.
+* PolyGerrit imports pluginname.html along with all required resources defined in it
+  (fonts, styles, etc).
 * For standalone plugins, the entry point file is a `pluginname.html` file
   located in `gerrit-site/plugins` folder, where `pluginname` is an alphanumeric
   plugin name.
 
-Here's a sample `myplugin.html`:
+Note: Code examples target modern brosers (Chrome, Firefox, Safari, Edge)
+
+Here's a recommended starter `myplugin.html`:
 
 ``` html
 <dom-module id="my-plugin">
   <script>
-    Gerrit.install(function() { console.log('Ready.'); });
+    Gerrit.install(plugin => {
+      'use strict';
+
+      // Your code here.
+    });
   </script>
 </dom-module>
 ```
@@ -46,7 +55,7 @@ element.
 4. Use element.content to get UI element
 
 ``` js
-Gerrit.install(function(plugin) {
+Gerrit.install(plugin => {
   const domHook = plugin.hook('reply-text');
   domHook.onAttached(element => {
     if (!element.content) { return; }
@@ -64,7 +73,7 @@ attributes and events) that are supported in the long-term.
 NOTE: TODO: Insert link to the full endpoints API.
 
 ``` js
-Gerrit.install(function(plugin) {
+Gerrit.install(plugin => {
   const domHook = plugin.hook('reply-text');
   domHook.onAttached(element => {
     if (!element.content) { return; }
@@ -80,7 +89,7 @@ An endpoint's contents can be replaced by passing the replace attribute as an
 option.
 
 ``` js
-Gerrit.install(function(plugin) {
+Gerrit.install(plugin => {
   const domHook = plugin.hook('header-title', {replace: true});
   domHook.onAttached(element => {
     element.appendChild(document.createElement('my-site-header'));
@@ -102,7 +111,7 @@ Note: TODO: Insert link to the full styling API.
 ``` html
 <dom-module id="my-plugin">
   <script>
-    Gerrit.install(function(plugin) {
+    Gerrit.install(plugin => {
       plugin.registerStyleModule('change-metadata', 'some-style-module');
     });
   </script>