From 29a0024a6152f479c313e6e1e4de0a0d767383d5 Mon Sep 17 00:00:00 2001
From: jcowman2 <joe.cowman@huskers.unl.edu>
Date: Mon, 26 Aug 2019 17:08:52 -0500
Subject: [PATCH] docs(agents): Add remaining docs for prototype registry
 refactor

---
 .../prototype/prototype-registry-impl-base.ts | 19 +++++++++++++++++++
 .../impl/prototype/prototype-registry-impl.ts | 10 ++++++++++
 .../static-prototype-registry-impl.ts         |  2 +-
 src/agents/prototype-registry.ts              | 11 +++++++++++
 4 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/src/agents/impl/prototype/prototype-registry-impl-base.ts b/src/agents/impl/prototype/prototype-registry-impl-base.ts
index 3a7c741..2cdb9ff 100644
--- a/src/agents/impl/prototype/prototype-registry-impl-base.ts
+++ b/src/agents/impl/prototype/prototype-registry-impl-base.ts
@@ -1,3 +1,12 @@
+/*
+ * Contains the abstract base class for `PrototypeRegistry` implementations,
+ * which implements the shared functionality between the static and non-static
+ * prototype registries.
+ *
+ * Copyright (c) Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import { PKProvider } from "../../../common";
 import { RegalError } from "../../../error";
 import { Agent } from "../../agent";
@@ -5,10 +14,17 @@ import { AgentProtoId } from "../../agent-meta";
 import { PrototypeRegistry } from "../../prototype-registry";
 import { getInstanceStateAgentProtoPK } from "./agent-proto-keys";
 
+/**
+ * Helper interface for the structure of `PrototypeRegistryImplBase`'s
+ * internal prototype store.
+ */
 export interface ProtoRegistryStore {
     [key: string]: object;
 }
 
+/**
+ * Abstract base class for `PrototypeRegistry`.
+ */
 export abstract class PrototypeRegistryImplBase implements PrototypeRegistry {
     constructor(protected _store: ProtoRegistryStore = {}) {}
 
@@ -60,5 +76,8 @@ export abstract class PrototypeRegistryImplBase implements PrototypeRegistry {
 
     public abstract copy(): PrototypeRegistry;
 
+    /**
+     * Returns the prototype registry's `AgentProtoId` `PKProvider`.
+     */
     protected abstract getProtoPKProvider(): PKProvider<AgentProtoId>;
 }
diff --git a/src/agents/impl/prototype/prototype-registry-impl.ts b/src/agents/impl/prototype/prototype-registry-impl.ts
index b0b3d29..665bc97 100644
--- a/src/agents/impl/prototype/prototype-registry-impl.ts
+++ b/src/agents/impl/prototype/prototype-registry-impl.ts
@@ -1,3 +1,10 @@
+/*
+ * Contains the non-static `PrototypeRegistry` implementation.
+ *
+ * Copyright (c) Joseph R Cowman
+ * Licensed under MIT License (see https://github.com/regal/regal)
+ */
+
 import { PKProvider } from "../../../common";
 import { AgentProtoId } from "../../agent-meta";
 import { PrototypeRegistry } from "../../prototype-registry";
@@ -13,6 +20,9 @@ export const buildPrototypeRegistry = (
     pkProvider: PKProvider<AgentProtoId>
 ): PrototypeRegistry => new PrototypeRegistryImpl(pkProvider);
 
+/**
+ * Non-static `PrototypeRegistry` implementation.
+ */
 class PrototypeRegistryImpl extends PrototypeRegistryImplBase {
     constructor(
         private _pkProvider: PKProvider<AgentProtoId>,
diff --git a/src/agents/impl/prototype/static-prototype-registry-impl.ts b/src/agents/impl/prototype/static-prototype-registry-impl.ts
index b6c414d..b6dc1ac 100644
--- a/src/agents/impl/prototype/static-prototype-registry-impl.ts
+++ b/src/agents/impl/prototype/static-prototype-registry-impl.ts
@@ -1,5 +1,5 @@
 /*
- * Contains the static `PrototypeRegistry` type definition and implementation.
+ * Contains the `StaticPrototypeRegistry` type definition and implementation.
  *
  * Copyright (c) Joseph R Cowman
  * Licensed under MIT License (see https://github.com/regal/regal)
diff --git a/src/agents/prototype-registry.ts b/src/agents/prototype-registry.ts
index 5929a3d..89a2615 100644
--- a/src/agents/prototype-registry.ts
+++ b/src/agents/prototype-registry.ts
@@ -36,10 +36,21 @@ export interface PrototypeRegistry {
      */
     newInstance(prototypeId: AgentProtoId): Agent;
 
+    /**
+     * Creates an agent from the registered prototype specified by the given id,
+     * using `Object.create()`. Returns `undefined` if no prototype exists with the id.
+     * @param prototypeId The prototype id.
+     */
     newInstanceOrDefault(prototypeId: AgentProtoId): Agent;
 
+    /**
+     * Gets the `protoId` which corresponds to the given prototype, or returns undefined
+     * if none exists.
+     * @param obj The `Agent` prototype.
+     */
     getPrototypeIdOrDefault(obj: Agent): AgentProtoId;
 
+    /** Makes a deep copy of this `PrototypeRegistry`. */
     copy(): PrototypeRegistry;
 }