Draft: Improve typedoc output

docs.css

@@ -1,5 +1,63 @@
-:root {
-	--dark-color-background: #222;
-	--dark-color-background-secondary: #191919;
-	--color-accent: #444;
+@layer typedoc, custom;
+
+@layer custom {
+	:root {
+		--dark-color-background: #222 !important;
+		--dark-color-background-secondary: #191919 !important;
+		--color-accent: #444 !important;
+		--color-link: #ff5b56 !important;
+		--color-active-menu-item: #aaa3 !important;
+
+		-webkit-font-smoothing: antialiased;
+		-moz-osx-font-smoothing: grayscale;
+		text-rendering: optimizeLegibility;
+	}
+
+	.tsd-breadcrumb li {
+		line-height: 1.95;
+		font-size: 10pt;
+		font-weight: medium;
+	}
+
+	.tsd-breadcrumb a {
+		color: light-dark(#444, #bbb);
+		text-decoration: none;
+		padding: 2px 6px;
+		border-radius: 3px;
+		background-color: light-dark(#6662, #bbb2);
+	}
+
+	.tsd-breadcrumb li::after {
+		content: "/";
+		padding: 0 4px;
+		position: relative;
+		top: -1px;
+
+		color: #888;
+	}
+
+	g.tsd-no-select rect {
+		rx: 4px;
+	}
+
+	g.tsd-no-select text {
+		transform: translate(-1%, -3%);
+		font-weight: bold;
+		/* fill: #ccc; */
+		font-size: 10pt;
+	}
+
+	.tsd-navigation .tsd-kind-icon ~ span {
+		/* --color-text: #ccc; */
+		opacity: 0.7;
+	}
+
+	.tsd-navigation .current {
+		border-radius: 5px;
+	}
+
+	.tsd-navigation .current .tsd-kind-icon ~ span {
+		/* --color-text: #fff; */
+		opacity: 1.0;
+	}
 }

p2ce/achievements.d.ts

@@ -1,4 +1,4 @@
-
+/** Defines the structure of a single achievement. */
 interface Achievement {
 	name: string;						// Name of the achievement
 	index: number;						// Index of the achievement (for use with the API)

p2ce/events.d.ts

@@ -1,5 +1,11 @@
 /**
- * @file P2:CE-specific event definitions.
+ * @example Declaring new events
+ * You can define new event types by redeclaring the GlobalEventNameMap interface with your new events. This is required when using Typescript and `ALLOW_MISSING_EVENTS` is `false`.
+ * ```js
+ * interface GlobalEventNameMap {
+ *   MyCustomEvent:    (yippee: boolean) => void;
+ * }
+ * ```
  */
 
 interface GlobalEventNameMap {

p2ce/weapons.d.ts

@@ -1,6 +1,4 @@
 /**
- * @packageDocumentation
- * P2:CE Weapons API.
  * @example Select the crowbar if the player has it.
  * ```
  * const crowbar = WeaponsAPI.GetWeaponIndexFromClass("weapon_crowbar");

p2ce/workshop.d.ts

@@ -1,6 +1,4 @@
 /**
- * @packageDocumentation
- * P2:CE Workshop API.
  * @example List all subscribed addons' names.
  * ```
  * const addon_count = WorkshopAPI.GetAddonCount();

package.json

@@ -3,5 +3,8 @@
 	"version": "1.0.0",
 	"description": "Near-full coverage of Panorama's APIs and data structures with Typescript definitions.",
 	"author": "Koerismo",
-	"license": "MIT"
+	"license": "MIT",
+	"devDependencies": {
+		"typedoc": "^0.26.11"
+	}
 }

shared/apis.d.ts

@@ -633,6 +633,7 @@ declare namespace UiToolkitAPI {
 	/** Show a popup on 'global popups top level window' that lets you specify a layout and parameters. */
 	function ShowGlobalCustomLayoutPopupParameters<T extends GenericPanel = GenericPanel>(popupID: string, layoutFile: string, parameters: string): T;
 
+	/** Defines a context menu item. Used by various UIToolkitAPI methods. */
 	interface SimpleContextMenuItem {
 		label: string;
 		jsCallback: () => void;

shared/events.d.ts

@@ -1,6 +1,5 @@
 /**
- * @file Defines built-in events from Panorama's events system
- * @see https://github.com/StrataSource/pano-typed/
+ * @packageDocumentation Defines built-in events from Panorama's events system
  */
 
 /** Defines built-in panel events from Panorama's events system. */

shared/index.d.ts

@@ -1,8 +1,11 @@
 /**
- * @packageDocumentation
- * Shared types.
+ * @packageDocumentation Shared types, present in all Strata games.
+ * See the {@link shared/apis | APIs module} for a full list of APIs.
+ * 
+ * For more information, see the [official documentation](https://wiki.stratasource.org/shared/panorama/overview).
  */
 
+/// <reference path="./primitives.d.ts" />
 /// <reference path="./panels.d.ts" />
 /// <reference path="./apis.d.ts" />
 /// <reference path="./style.d.ts" />
@@ -85,11 +88,11 @@ declare type JsonObject = { [Key in string]: JsonValue } & { [Key in string]?: J
 declare type JsonArray = JsonValue[] | readonly JsonValue[];
 declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 
-/** Encourages IDEs to flatten types when displaying. */
+/** @internal Encourages IDEs to flatten types when displaying. */
 declare type Simplify<T> = { [Key in keyof T]: T[Key] } & {};
 
-/** Make a type incompatible with types that'd otherwise be compatible. */
+/** @internal Make a type incompatible with types that'd otherwise be compatible. */
 declare type Brand<Type, Brand> = Type & { __brand: Brand };
 
-/** Type to signify flags/bitfield of some enum, ultimately just a `number`. */
+/** @internal Type to signify flags/bitfield of some enum, ultimately just a `number`. */
 declare type Flags<_Enum, Underlying = number> = Underlying;

shared/panels.d.ts

@@ -245,13 +245,25 @@ declare interface AbstractPanel<PanelName extends keyof PanelTagNameMap> {
 
 	SetAttributeUInt32(attribute: string, value: uint32): void;
 
-	SetDialogVariable(arg0: string, arg1: string): void;
+	/** Sets a dialog variable for the Panel.
+	 * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables)
+	 */
+	SetDialogVariable(variable: string, value: string): void;
 
-	SetDialogVariableFloat(arg0: string, arg1: float): void;
+	/** Sets a float dialog variable for the Panel.
+	 * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables)
+	 */
+	SetDialogVariableFloat(variable: string, value: float): void;
 
-	SetDialogVariableInt(arg0: string, arg1: int32): void;
+	/** Sets an integer dialog variable for the Panel.
+	 * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables)
+	 */
+	SetDialogVariableInt(variable: string, value: int32): void;
 
-	SetDialogVariableTime(arg0: string, arg1: int64_num | int64_str): void;
+	/** Sets a time dialog variable for the Panel.
+	 * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables)
+	 */
+	SetDialogVariableTime(variable: string, value: int64_num | int64_str): void;
 
 	SetDisableFocusOnMouseDown(istrue: boolean): void;
 

shared/primitives.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @packageDocumentation Simple primitive types, separated to keep documentation clean.
+ */
+
+declare type float = number;
+declare type double = number;
+
+declare type uint8 = number;
+declare type uint16 = number;
+declare type uint32 = number;
+
+declare type int8 = number;
+declare type int16 = number;
+declare type int32 = number;
+
+/**
+ * A STRING representing an int64.
+ *
+ * JavaScript `number`s are IEEE floats and lose precision when used for values greater than 2^53. Most of Panorama was
+ * implemented before native JS BigInts were a thing, and not worth the refactoring work to use them.
+ *
+ * In C++, when a C++ method/events exposed to JS have a int64/uint64 param, either a number or string can be passed
+ * from JS, and both will be converted to the corresponding 64-bit integer. If precision is a concern (e.g. SteamIDs),
+ * use a string.
+ *
+ * For methods/events that *return* a int64/uint64, Panorama will return a JS string!
+ *
+ * To be super explicit this, we have separate type aliases for both numbers and strings. When typing C++ methods,
+ * those taking int64 params in C++ should have TS params with type `int64_str | int64_num`, whilst methods returning
+ * `int64`s from C++ should return only `int64_str` in TS.
+ */
+declare type int64_str = string;
+
+/** @see {int64_str} */
+declare type int64_num = number;
+
+/** @see {int64_str} */
+declare type uint64_str = string;
+
+/** @see {int64_str} */
+declare type uint64_num = number;
+
+/**
+ * String of a SteamID64. Might look like a uint64 in C++ but it's always a string in JS!
+ * @see {int64_str}
+ */
+declare type steamID = string;
+
+declare type vec2 = { x: number; y: number };
+declare type vec3 = { x: number; y: number; z: number };
+
+/** A duration in seconds. */
+declare type duration = number;
+
+/** Represents a unique id return. */
+declare type uuid = int32;
+
+/** Represents a keyframes animation return. */
+declare type Keyframes = unknown;
+
+/** rgba, hex etc. color string */
+declare type color = string;
+
+/** rgba color string */
+declare type rgbaColor = string;
+
+// ======== Utility Types ========
+// Many of these are from https://github.com/sindresorhus/type-fest
+// We'd rather avoid the dependency, but feel free to pinch stuff from there.
+
+declare type Func<Args extends unknown[] = any[], Return = void> = (...args: Args) => Return;
+declare type ValueOf<T> = T[keyof T];
+declare type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+
+declare type JsonPrimitive = string | number | boolean | null;
+declare type JsonObject = { [Key in string]: JsonValue } & { [Key in string]?: JsonValue | undefined };
+declare type JsonArray = JsonValue[] | readonly JsonValue[];
+declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+/** @internal Encourages IDEs to flatten types when displaying. */
+declare type Simplify<T> = { [Key in keyof T]: T[Key] } & {};
+
+/** @internal Make a type incompatible with types that'd otherwise be compatible. */
+declare type Brand<Type, Brand> = Type & { __brand: Brand };
+
+/** @internal Type to signify flags/bitfield of some enum, ultimately just a `number`. */
+declare type Flags<_Enum, Underlying = number> = Underlying;

shared/style.d.ts

@@ -1,6 +1,5 @@
 /**
- * @file Defines style properties accessible through scripting
- * @see https://github.com/StrataSource/pano-typed/
+ * @packageDocumentation Defines style properties accessible through scripting
  */
 
 /** Generic panel styling properties. */

tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"rootDir": "./",
+		"noEmit": true
+	},
+	"include": ["p2ce", "shared"]
+}

typedoc.json

@@ -1,15 +1,19 @@
 {
 	"basePath": "./",
+	"name": "Strata Panorama Types",
 	"entryPoints": ["shared/**/*.d.ts", "p2ce/**/*.d.ts"],
 	"customCss": "docs.css",
 	"searchInComments": true,
+	"excludeInternal": true,
 	"kindSortOrder": [
 		"Module",
 		"Namespace",
 		"Function",
 		"Class",
 		"Interface",
 		"Property",
+		"TypeAlias",
+		"TypeLiteral"
 	],
 	"searchGroupBoosts": {
 		"api": 30,