Clean up top-level docs

* Include the README in generated JS docs.
* Tweak stray top-level files to explain their role.  Note that the
wmf template forces these files to appear on the docs home page...

Bug: T358641
Change-Id: If421414340903991f50a06a76551bd7cd2904c5e

README.md

@@ -1,6 +1,8 @@
-Cite
+The Cite extension to MediaWiki provides a way for wiki editors to add references and footnotes to articles.
-=============
 
-The Cite extension provides a way for users to create references as footnotes to articles.
+See [mw:Extension:Cite] for technical documentation on installing and configuring the extension.  See [mw:Help:Cite] for user documentation.
 
-See https://www.mediawiki.org/wiki/Extension:Cite for detailed documentation.
+Cite is responsible for implementing the `<ref>` and `<references>` tags in wikitext.  Integrations are provided for the legacy wikitext parser, Parsoid, WikiEditor, VisualEditor, and the reading interface.
+
+[mw:Extension:Cite]: https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:Cite
+[mw:Help:Cite]: https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Cite

jsdoc.json

@@ -1,7 +1,6 @@
 {
 	"opts": {
 		"destination": "docs/js",
-		"package": "package.json",
 		"pedantic": true,
 		"recurse": true,
 		"template": "node_modules/jsdoc-wmf-theme"
@@ -10,7 +9,7 @@
 		"plugins/markdown"
 	],
 	"source": {
-		"include": [ "modules", "src" ]
+		"include": [ "modules", "package.json", "README.md" ]
 	},
 	"templates": {
 		"cleverLinks": true,

modules/ext.cite.a11y.js

@@ -1,10 +1,8 @@
 'use strict';
 
 /**
- * Main JavaScript for the Cite extension. The main purpose of this file
+ * @file Adds accessibility attributes to citation links.
- * is to add accessibility attributes to the citation links as that can
+ * @see https://phabricator.wikimedia.org/T40141
- * hardly be done server side (T40141).
- *
  * @author Marius Hoch <hoo@online.de>
  */
 mw.hook( 'wikipage.content' ).add( function ( $content ) {

modules/ext.cite.highlighting.js

@@ -1,6 +1,7 @@
 'use strict';
 
 /**
+ * @file Dynamic highlighting while reading an article
  * @author Thiemo Kreuz
  */
 ( function () {

modules/ext.cite.wikiEditor.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Add Cite-specific functionality to the WikiEditor toolbar.
+ * @file Add Cite-specific functionality to the WikiEditor toolbar.
  * Adds a button to insert <ref> tags, and adds a help section
  * about how to use references to WikiEditor's help panel.
  *