web: Document the modules

web/eslint.config.js

@@ -115,6 +115,10 @@ export default tseslint.config(
                     startLines: 1,
                 },
             ],
+            "jsdoc/check-tag-names": [
+                "error",
+                { definedTags: ["privateRemarks"] },
+            ],
         },
         settings: {
             jsdoc: {

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%",

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";

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";

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";

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.

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";