Split decorators into multiple files, add typedocs

src/features/achievements/achievement.tsx

@@ -1,5 +1,5 @@
 import AchievementComponent from "features/achievements/Achievement.vue";
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import {
     CoercableComponent,
     Component,

src/features/action.tsx

@@ -31,7 +31,7 @@ import { coerceComponent, isCoercableComponent, render } from "util/vue";
 import { computed, Ref, ref, unref } from "vue";
 import { BarOptions, createBar, GenericBar } from "./bars/bar";
 import { ClickableOptions } from "./clickables/clickable";
-import { Decorator } from "./decorators";
+import { Decorator } from "./decorators/common";
 
 export const ActionType = Symbol("Action");
 

src/features/bars/bar.ts

@@ -1,5 +1,5 @@
 import BarComponent from "features/bars/Bar.vue";
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import type {
     CoercableComponent,
     GenericComponent,

src/features/challenges/challenge.tsx

@@ -1,7 +1,7 @@
 import { isArray } from "@vue/shared";
 import Toggle from "components/fields/Toggle.vue";
 import ChallengeComponent from "features/challenges/Challenge.vue";
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import type { CoercableComponent, OptionsFunc, Replace, StyleValue } from "features/feature";
 import {
     Component,

src/features/clickables/clickable.ts

@@ -1,5 +1,5 @@
 import ClickableComponent from "features/clickables/Clickable.vue";
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import type {
     CoercableComponent,
     GenericComponent,

src/features/conversion.ts

@@ -11,7 +11,7 @@ import { convertComputable, processComputable } from "util/computed";
 import { createLazyProxy } from "util/proxies";
 import type { Ref } from "vue";
 import { computed, unref } from "vue";
-import { Decorator } from "./decorators";
+import { Decorator } from "./decorators/common";
 
 /** An object that configures a {@link Conversion}. */
 export interface ConversionOptions {

src/features/decorators/bonusDecorator.ts

@@ -1,44 +1,9 @@
-import { Replace, OptionsObject } from "./feature";
-import Decimal, { DecimalSource } from "util/bignum";
-import { Computable, GetComputableType, processComputable, ProcessedComputable } from "util/computed";
-import { Persistent, State } from "game/persistence";
-import { computed, Ref, unref } from "vue";
+import { Replace } from "features/feature";
+import Decimal, { DecimalSource } from "lib/break_eternity";
+import { Computable, GetComputableType, ProcessedComputable, processComputable } from "util/computed";
+import { Ref, computed, unref } from "vue";
+import { Decorator } from "./common";
 
-/*----====----*/
-
-export type Decorator<FeatureOptions, BaseFeature = {}, GenericFeature = {}, S extends State = State> = {
-    getPersistentData?(): Record<string, Persistent<S>>;
-    preConstruct?(feature: OptionsObject<FeatureOptions,BaseFeature,GenericFeature>): void;
-    postConstruct?(feature: OptionsObject<FeatureOptions,BaseFeature,GenericFeature>): void;
-    getGatheredProps?(feature: OptionsObject<FeatureOptions,BaseFeature,GenericFeature>): Partial<OptionsObject<FeatureOptions,BaseFeature,GenericFeature>>
-}
-
-/*----====----*/
-
-// #region Effect Decorator
-export interface EffectFeatureOptions {
-    effect: Computable<any>;
-}
-
-export type EffectFeature<T extends EffectFeatureOptions> = Replace<
-    T, { effect: GetComputableType<T["effect"]>; }
->;
-
-export type GenericEffectFeature = Replace<
-    EffectFeature<EffectFeatureOptions>,
-    { effect: ProcessedComputable<any>; }
->;
-
-export const effectDecorator: Decorator<EffectFeatureOptions, {}, GenericEffectFeature> = {
-    postConstruct(feature) {
-        processComputable(feature, "effect");
-    }
-}
-// #endregion
-
-/*----====----*/
-
-// #region Bonus Amount/Completions Decorator
 export interface BonusAmountFeatureOptions {
     bonusAmount: Computable<DecimalSource>;
 }
@@ -77,6 +42,16 @@ export type GenericBonusCompletionsFeature = Replace<
     }
 >;
 
+/**
+ * Allows the addition of "bonus levels" to the decorated feature, with an accompanying "total amount".  
+ * To function properly, the `createFeature()` function must have its generic type extended by {@linkcode BonusAmountFeatureOptions}.  
+ * To allow access to the decorated values outside the `createFeature()` function, the output type must be extended by {@linkcode GenericBonusAmountFeature}.
+ * @example ```ts
+ * createRepeatable<RepeatableOptions & BonusAmountFeatureOptions>(() => ({
+ *   bonusAmount: noPersist(otherRepeatable.amount),
+ *   ...
+ * }), bonusAmountDecorator) as GenericRepeatable & GenericBonusAmountFeature
+ */
 export const bonusAmountDecorator: Decorator<BonusAmountFeatureOptions, BaseBonusAmountFeature, GenericBonusAmountFeature> = {
     postConstruct(feature) {
         processComputable(feature, "bonusAmount");
@@ -88,18 +63,25 @@ export const bonusAmountDecorator: Decorator<BonusAmountFeatureOptions, BaseBonu
         }
     }
 }
-export const bonusCompletionsDecorator: Decorator<BonusAmountFeatureOptions, BaseBonusCompletionsFeature, GenericBonusCompletionsFeature> = {
+
+/**
+ * Allows the addition of "bonus levels" to the decorated feature, with an accompanying "total amount".  
+ * To function properly, the `createFeature()` function must have its generic type extended by {@linkcode BonusCompletionFeatureOptions}.  
+ * To allow access to the decorated values outside the `createFeature()` function, the output type must be extended by {@linkcode GenericBonusCompletionFeature}.
+ * @example ```ts
+ * createChallenge<ChallengeOptions & BonusCompletionFeatureOptions>(() => ({
+ *   bonusCompletions: noPersist(otherChallenge.completions),
+ *   ...
+ * }), bonusCompletionDecorator) as GenericChallenge & GenericBonusCompletionFeature
+ */
+export const bonusCompletionsDecorator: Decorator<BonusCompletionsFeatureOptions, BaseBonusCompletionsFeature, GenericBonusCompletionsFeature> = {
     postConstruct(feature) {
-        processComputable(feature, "bonusAmount");
+        processComputable(feature, "bonusCompletions");
         if (feature.totalCompletions === undefined) {
             feature.totalCompletions = computed(() => Decimal.add(
                 unref(feature.completions ?? 0),
-                unref(feature.bonusAmount as ProcessedComputable<DecimalSource>)
+                unref(feature.bonusCompletions as ProcessedComputable<DecimalSource>)
             ));
         }
     }
 }
-// #endregion
-
-/*----====----*/
-

src/features/decorators/common.ts

@@ -0,0 +1,49 @@
+import { Replace, OptionsObject } from "../feature";
+import { Computable, GetComputableType, processComputable, ProcessedComputable } from "util/computed";
+import { Persistent, State } from "game/persistence";
+
+/*----====----*/
+
+export type Decorator<FeatureOptions, BaseFeature = {}, GenericFeature = {}, S extends State = State> = {
+    getPersistentData?(): Record<string, Persistent<S>>;
+    preConstruct?(feature: OptionsObject<FeatureOptions,BaseFeature,GenericFeature>): void;
+    postConstruct?(feature: OptionsObject<FeatureOptions,BaseFeature,GenericFeature>): void;
+    getGatheredProps?(feature: OptionsObject<FeatureOptions,BaseFeature,GenericFeature>): Partial<OptionsObject<FeatureOptions,BaseFeature,GenericFeature>>
+}
+
+/*----====----*/
+
+// #region Effect Decorator
+export interface EffectFeatureOptions {
+    effect: Computable<any>;
+}
+
+export type EffectFeature<T extends EffectFeatureOptions> = Replace<
+    T, { effect: GetComputableType<T["effect"]>; }
+>;
+
+export type GenericEffectFeature = Replace<
+    EffectFeature<EffectFeatureOptions>,
+    { effect: ProcessedComputable<any>; }
+>;
+
+/**
+ * Allows the usage of an `effect` field in the decorated feature.  
+ * To function properly, the `createFeature()` function must have its generic type extended by {@linkcode EffectFeatureOptions}.  
+ * To allow access to the decorated values outside the `createFeature()` function, the output type must be extended by {@linkcode GenericEffectFeature}.
+ * @example ```ts
+ * createRepeatable<RepeatableOptions & EffectFeatureOptions>(() => ({
+ *   effect() { return Decimal.pow(2, this.amount); },
+ *   ...
+ * }), effectDecorator) as GenericUpgrade & GenericEffectFeature;
+ * ```
+ */
+export const effectDecorator: Decorator<EffectFeatureOptions, {}, GenericEffectFeature> = {
+    postConstruct(feature) {
+        processComputable(feature, "effect");
+    }
+}
+// #endregion
+
+/*----====----*/
+

src/features/milestones/milestone.tsx

@@ -1,5 +1,5 @@
 import Select from "components/fields/Select.vue";
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import type {
     CoercableComponent,
     GenericComponent,

src/features/repeatable.tsx

@@ -24,7 +24,7 @@ import { createLazyProxy } from "util/proxies";
 import { coerceComponent, isCoercableComponent } from "util/vue";
 import type { Ref } from "vue";
 import { computed, unref } from "vue";
-import { Decorator, GenericBonusAmountFeature } from "./decorators";
+import { Decorator } from "./decorators/common";
 
 /** A symbol used to identify {@link Repeatable} features. */
 export const RepeatableType = Symbol("Repeatable");

src/features/trees/tree.ts

@@ -1,4 +1,4 @@
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import type { CoercableComponent, OptionsFunc, Replace, StyleValue } from "features/feature";
 import { Component, GatherProps, getUniqueID, setDefault, Visibility } from "features/feature";
 import type { Link } from "features/links/links";

src/features/upgrades/upgrade.ts

@@ -1,5 +1,5 @@
 import { isArray } from "@vue/shared";
-import { Decorator } from "features/decorators";
+import { Decorator } from "features/decorators/common";
 import type {
     CoercableComponent,
     GenericComponent,
@@ -15,11 +15,13 @@ import {
     setDefault,
     Visibility
 } from "features/feature";
+import { createResource } from "features/resources/resource";
 import UpgradeComponent from "features/upgrades/Upgrade.vue";
 import type { GenericLayer } from "game/layers";
 import type { Persistent } from "game/persistence";
 import { persistent } from "game/persistence";
 import {
+createCostRequirement,
     createVisibilityRequirement,
     payRequirements,
     Requirements,