From ba137fba8852eb2b61db36c035896cbb144da66b Mon Sep 17 00:00:00 2001
From: Adam Wight <adam.wight@wikimedia.de>
Date: Tue, 12 Mar 2024 09:37:44 +0100
Subject: [PATCH] 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                        | 10 ++++++----
 jsdoc.json                       |  3 +--
 modules/ext.cite.a11y.js         |  6 ++----
 modules/ext.cite.highlighting.js |  1 +
 modules/ext.cite.wikiEditor.js   |  2 +-
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 180c92b34..629e7b3a5 100644
--- a/README.md
+++ b/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
diff --git a/jsdoc.json b/jsdoc.json
index 93f6f96d3..8b314b481 100644
--- a/jsdoc.json
+++ b/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,
diff --git a/modules/ext.cite.a11y.js b/modules/ext.cite.a11y.js
index 327f0f128..31b349b9a 100644
--- a/modules/ext.cite.a11y.js
+++ b/modules/ext.cite.a11y.js
@@ -1,10 +1,8 @@
 'use strict';
 
 /**
- * Main JavaScript for the Cite extension. The main purpose of this file
- * is to add accessibility attributes to the citation links as that can
- * hardly be done server side (T40141).
- *
+ * @file Adds accessibility attributes to citation links.
+ * @see https://phabricator.wikimedia.org/T40141
  * @author Marius Hoch <hoo@online.de>
  */
 mw.hook( 'wikipage.content' ).add( function ( $content ) {
diff --git a/modules/ext.cite.highlighting.js b/modules/ext.cite.highlighting.js
index 18a0c97b7..7096f72f3 100644
--- a/modules/ext.cite.highlighting.js
+++ b/modules/ext.cite.highlighting.js
@@ -1,6 +1,7 @@
 'use strict';
 
 /**
+ * @file Dynamic highlighting while reading an article
  * @author Thiemo Kreuz
  */
 ( function () {
diff --git a/modules/ext.cite.wikiEditor.js b/modules/ext.cite.wikiEditor.js
index 652fa485e..e72262f7f 100644
--- a/modules/ext.cite.wikiEditor.js
+++ b/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.
  *