Reorganise developer docs

corewar · Sep 5, 2018 · 8abda54 · 8abda54
1 parent 2010ec8
commit 8abda54
Show file tree

Hide file tree

Showing 6 changed files with 145 additions and 129 deletions.
diff --git a/docs/developer/index.md b/docs/developer/index.md
@@ -1,140 +1,20 @@
-Developer Reference
-===================
+# Corewar Developer Reference
 
 This area of the docs will provides a technical reference for the corewar npm package.
 
 * [Corewar GitHub page](https://github.com/gareththegeek/corewar)
 * [Corewar NPM package](https://www.npmjs.com/package/corewar)
 
-## API
+The Corewar library provides a redcode parser, corewar simulator and hill and benchmark functionality and is used by [corewar.io](https://corewar.io).
 
-The API exposes the following functions and pubsub events:
+The Corewar library provides an API to access the libraries functionality. The library uses a pubsub mechanism to publish messages in resopnse to events within the simulator.
 
-### parse(redcode: string): IParseResult
+The developer reference contains the following sections:
 
-Parse a redcode document and return an IParseResult which consists of the tokenised program and any associated messages.
-
-### initialiseSimulator(options: IOptions, parseResults: IParseResult[], messageProvider: IPublishProvider)
-
-Setup the simulator for a specific standard and parseResult (parsed redcode).
-IParseResults are produced as output from the Parser module.
-Additional, data can be associated with a warrior when it is loaded into core by adding a data property to the parseResults given to the initialise function.
-Allows a pubsub provider to be specified to receive Events (see below).
-
-### step(steps?: number): boolean
-
-Step the simulator forward number of cycles specified by steps (default 1).
-Returns false if the round has ended.
-
-### run()
-
-Run the simulator to the end of the match
-
-### getWithInfoAt(address: number): ICoreLocation
-
-Return the instruction at the specified core address.
-
-### serialise(tokens: IToken[]): string
-
-Serialises the array of tokens to a single, human readable string.
-
-### republish(): void
-
-Trigger a resending of all pubsub messages for the current round.
-This can be used to build up a picture of the current state of the simulator from scratch.
-
-## Events
-
-Beyond the main API, the following messages are available to subscribe to:
-
-### CORE_INITIALISE
-
-Contains the initial state of the simulator core and process tree.
-
-```
-{
-  state: IState
-}
-```
-
-### CORE_ACCESS
-
-Published when a warrior reads to, writes from or executes within the core
-
-```
-[{
-  warriorId: number,      // Each warrior has a unique id
-  warriorData?: any,      // Any data supplied with this warrior's initial parse result
-  accessType: AccessType, // AccessType can be 0=read, 1=write or 2=execute
-  address: number         // Absolute address within the core
-}]
-```
-
-### RUN_PROGRESS
-
-Used to monitor progress towards the end of the round
-
-```
-{ 
-  runProgress: number   // Indicates current cycle as a percentage of maximum cycles
-  cycle: number         // The current cycle
-  maximumCycles: number // The maximum number of cycles, after which the round will end in a draw
-}
-```
-
-### ROUND_END
-
-Published at the end of the round to indicate the outcome
-
-```
-{
-  winnerId: number,  // The unique id of the winning warrior or null
-  winnerData?: any,  // Any data supplied with this warrior's initial parse result
-  outcome: string    // Can be 'WIN', 'DRAW' or 'NONE'. 'NONE' indicates a single warrior battle
-}
-```
-
-### MATCH_END
-
-Published at the end of a multi-round match to indicate the outcome
-
-```
-{
-  rounds: number;   // The number of rounds in the match
-  warriors: [
-    source: IParseResult;   // The parsed output of the warrior
-    won: number;            // The number of rounds won by the warrior
-    drawn: number;          // The number of rounds drawn by the warrior
-    lost: number;           // The number of rounds lost by the warrior
-    given: number;          // The number of points awarded to the warrior given by win percentage multiplied by three plus draw percentage
-    taken: number;          // The number of points awarded to the warrior's opponent given by loss percentage multiplied by three plus draw percentage
-  ];
-}
-```
-
-### TASK_COUNT
-
-Published whenever a warrior creates or loses a task.
-
-```
-[{
-  warriorId: number,  // The unique id of the warrior
-  warriorData?: any,  // Any data supplied with this warrior's initial parse result
-  taskCount: number   // The warrior's current task count
-}]
-```
-
-### NEXT_EXECUTION
-
-Published once per call to step and indicates the next address which will be executed
-
-```
-{
-  warriorId: number,  // The unique id of the next warrior
-  warriorData?: any,  // Any data supplied with this warrior's initial parse result
-  address: number     // The address in core at which the next warrior will execute
-}
-```
+* [Parser](./parser)
+* [Simulator](./simulator)
+* [Matches](./matches)
+* [Messages](./messages)
 
 ## Testing
 

diff --git a/docs/developer/matches.md b/docs/developer/matches.md
@@ -0,0 +1,2 @@
+# Matches API
+
diff --git a/docs/developer/messages.md b/docs/developer/messages.md
@@ -0,0 +1,92 @@
+# Messages
+
+Beyond the main API, the following messages are available to subscribe to:
+
+## CORE_INITIALISE
+
+Contains the initial state of the simulator core and process tree.
+
+```
+{
+  state: IState
+}
+```
+
+## CORE_ACCESS
+
+Published when a warrior reads to, writes from or executes within the core
+
+```
+[{
+  warriorId: number,      // Each warrior has a unique id
+  warriorData?: any,      // Any data supplied with this warrior's initial parse result
+  accessType: AccessType, // AccessType can be 0=read, 1=write or 2=execute
+  address: number         // Absolute address within the core
+}]
+```
+
+## RUN_PROGRESS
+
+Used to monitor progress towards the end of the round
+
+```
+{ 
+  runProgress: number   // Indicates current cycle as a percentage of maximum cycles
+  cycle: number         // The current cycle
+  maximumCycles: number // The maximum number of cycles, after which the round will end in a draw
+}
+```
+
+## ROUND_END
+
+Published at the end of the round to indicate the outcome
+
+```
+{
+  winnerId: number,  // The unique id of the winning warrior or null
+  winnerData?: any,  // Any data supplied with this warrior's initial parse result
+  outcome: string    // Can be 'WIN', 'DRAW' or 'NONE'. 'NONE' indicates a single warrior battle
+}
+```
+
+## MATCH_END
+
+Published at the end of a multi-round match to indicate the outcome
+
+```
+{
+  rounds: number;   // The number of rounds in the match
+  warriors: [
+    source: IParseResult;   // The parsed output of the warrior
+    won: number;            // The number of rounds won by the warrior
+    drawn: number;          // The number of rounds drawn by the warrior
+    lost: number;           // The number of rounds lost by the warrior
+    given: number;          // The number of points awarded to the warrior given by win percentage multiplied by three plus draw percentage
+    taken: number;          // The number of points awarded to the warrior's opponent given by loss percentage multiplied by three plus draw percentage
+  ];
+}
+```
+
+## TASK_COUNT
+
+Published whenever a warrior creates or loses a task.
+
+```
+[{
+  warriorId: number,  // The unique id of the warrior
+  warriorData?: any,  // Any data supplied with this warrior's initial parse result
+  taskCount: number   // The warrior's current task count
+}]
+```
+
+## NEXT_EXECUTION
+
+Published once per call to step and indicates the next address which will be executed
+
+```
+{
+  warriorId: number,  // The unique id of the next warrior
+  warriorData?: any,  // Any data supplied with this warrior's initial parse result
+  address: number     // The address in core at which the next warrior will execute
+}
+```
diff --git a/docs/developer/parser.md b/docs/developer/parser.md
@@ -0,0 +1,11 @@
+# Parser API
+
+The API exposes the following functions and pubsub events:
+
+## parse(redcode: string): IParseResult
+
+Parse a redcode document and return an IParseResult which consists of the tokenised program and any associated messages.
+
+## serialise(tokens: IToken[]): string
+
+Serialises the array of tokens to a single, human readable string.
diff --git a/docs/developer/simulator.md b/docs/developer/simulator.md
@@ -0,0 +1,26 @@
+# Simulator API
+
+## initialiseSimulator(options: IOptions, parseResults: IParseResult[], messageProvider: IPublishProvider)
+
+Setup the simulator for a specific standard and parseResult (parsed redcode).
+IParseResults are produced as output from the Parser module.
+Additional, data can be associated with a warrior when it is loaded into core by adding a data property to the parseResults given to the initialise function.
+Allows a pubsub provider to be specified to receive Events (see below).
+
+## step(steps?: number): boolean
+
+Step the simulator forward number of cycles specified by steps (default 1).
+Returns false if the round has ended.
+
+## run()
+
+Run the simulator to the end of the match
+
+## getWithInfoAt(address: number): ICoreLocation
+
+Return the instruction at the specified core address.
+
+## republish(): void
+
+Trigger a resending of all pubsub messages for the current round.
+This can be used to build up a picture of the current state of the simulator from scratch.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -26,5 +26,10 @@ pages:
    - Preprocessor: redcode/preprocessor.md
    - Comments: redcode/comments.md
    - Metadata: redcode/metadata.md
-- Developer Reference: developer/index.md
+- Developer Reference:
+   - Intro: developer/index.md
+   - Parser: developer/parser.md
+   - Simulator: developer/simulator.md
+   - Matches: developer/matches.md
+   - Messages: developer/messages.md
 theme: readthedocs