From 531ef4382b7af8a380a12ae8092c2f19778cec23 Mon Sep 17 00:00:00 2001
From: Nathan Adams <dinnerbone@dinnerbone.com>
Date: Thu, 3 Oct 2024 01:20:45 +0200
Subject: [PATCH] web: Document the modules

---
 web/eslint.config.js                            |  4 ++++
 web/packages/core/src/build-info.ts             |  7 ++++++-
 web/packages/core/src/index.ts                  |  9 +++------
 web/packages/core/src/public/config/index.ts    |  9 +++++++++
 web/packages/core/src/public/player/index.ts    |  6 ++++++
 .../core/src/public/player/player-element.ts    |  2 +-
 web/packages/core/src/public/setup/index.ts     | 17 +++++++++++++++++
 7 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/web/eslint.config.js b/web/eslint.config.js
index 3be1b21708e2..daba5c146add 100644
--- a/web/eslint.config.js
+++ b/web/eslint.config.js
@@ -115,6 +115,10 @@ export default tseslint.config(
                     startLines: 1,
                 },
             ],
+            "jsdoc/check-tag-names": [
+                "error",
+                { definedTags: ["privateRemarks"] },
+            ],
         },
         settings: {
             jsdoc: {
diff --git a/web/packages/core/src/build-info.ts b/web/packages/core/src/build-info.ts
index d6cf11db2ea4..7fda18c68e1d 100644
--- a/web/packages/core/src/build-info.ts
+++ b/web/packages/core/src/build-info.ts
@@ -1,5 +1,10 @@
 /**
- * Stores build information. The string literals are replaced at compile time by `set_version.ts`.
+ * Stores build information about <b>this specific version of the `ruffle-core` library</b>.
+ *
+ * It does not represent the version of Ruffle that may be in use by the page (for example, if a browser extension overrides it).
+ *
+ * @privateRemarks
+ * This is generated at build time via `set_version.ts`.
  */
 export const buildInfo = {
     versionNumber: "%VERSION_NUMBER%",
diff --git a/web/packages/core/src/index.ts b/web/packages/core/src/index.ts
index 6dd20d598c82..f7b900ea9026 100644
--- a/web/packages/core/src/index.ts
+++ b/web/packages/core/src/index.ts
@@ -1,10 +1,7 @@
-/**
- * This is the public API of the web version of Ruffle.
- *
- * Types should only be exported here if they are intended to be part of that public API, not internal.
- */
-
 export * as Setup from "./public/setup";
+
 export * as Config from "./public/config";
+
 export * as Player from "./public/player";
+
 export * from "./build-info";
diff --git a/web/packages/core/src/public/config/index.ts b/web/packages/core/src/public/config/index.ts
index 50157bea6391..5a1ae261d316 100644
--- a/web/packages/core/src/public/config/index.ts
+++ b/web/packages/core/src/public/config/index.ts
@@ -1,2 +1,11 @@
+/**
+ * The Config module contains all the types that Ruffle uses for movie configs.
+ *
+ * The main interface of interest here is {@link BaseLoadOptions}, which you can apply to `window.RufflePlayer.config`
+ * to set the default configuration of all players.
+ *
+ * @module
+ */
+
 export * from "./default";
 export * from "./load-options";
diff --git a/web/packages/core/src/public/player/index.ts b/web/packages/core/src/public/player/index.ts
index ad6d0359ccd5..0ef102322544 100644
--- a/web/packages/core/src/public/player/index.ts
+++ b/web/packages/core/src/public/player/index.ts
@@ -1,3 +1,9 @@
+/**
+ * The Player module contains the actual {@link PlayerElement} and the various interfaces that exist to interact with the player.
+ *
+ * @module
+ */
+
 export * from "./flash";
 export * from "./player-element";
 export * from "./movie-metadata";
diff --git a/web/packages/core/src/public/player/player-element.ts b/web/packages/core/src/public/player/player-element.ts
index ed9a879568b5..97b663382b6d 100644
--- a/web/packages/core/src/public/player/player-element.ts
+++ b/web/packages/core/src/public/player/player-element.ts
@@ -4,7 +4,7 @@ import { FlashAPI } from "./flash";
 /**
  * A Ruffle player's HTML element.
  *
- * This is either created through `window.RufflePlayer.createPlayer()`, or polyfilled from a `<embed>`/`<object>` tag.
+ * This is either created through `window.RufflePlayer.latest().createPlayer()`, or polyfilled from a `<embed>`/`<object>` tag.
  *
  * In addition to usual HTML attributes, this player contains methods and properties that belong to both
  * the **Flash JS API** and **legacy Ruffle API**s.
diff --git a/web/packages/core/src/public/setup/index.ts b/web/packages/core/src/public/setup/index.ts
index 81bd21de1427..eb86b3c22c21 100644
--- a/web/packages/core/src/public/setup/index.ts
+++ b/web/packages/core/src/public/setup/index.ts
@@ -1,3 +1,20 @@
+/**
+ * The Setup module contains the interfaces and methods needed to install Ruffle onto a page,
+ * and create a {@link PlayerElement} with the latest version of Ruffle available.
+ *
+ * This is primarily relevant to users of `ruffle-core` as a npm module, as the "selfhosted" version of Ruffle preinstalls itself,
+ * and without type checking the interfaces here are of limited use.
+ *
+ * For users of `ruffle-core` as a npm module, you are encouraged to call {@link installRuffle} once during page load to
+ * make the `ruffle-core` library register itself as a version of Ruffle on the page.
+ *
+ * Multiple sources of Ruffle may exist - for example, the Ruffle browser extension also installs itself on page load.
+ * For this reason, you are required to call `window.RufflePlayer.latest()` (for example) to grab the latest {@link SourceAPI},
+ * from which you can create a {@link PlayerElement} via {@link SourceAPI.createPlayer}.
+ *
+ * @module
+ */
+
 export * from "./public-api";
 export * from "./source-api";
 export * from "./install";