From 93cbe88060c975e568d629f43928dd38555bb06a Mon Sep 17 00:00:00 2001
From: Bruno Dias <bruno.r.dias@gmail.com>
Date: Mon, 4 May 2015 13:26:49 -0300
Subject: [PATCH] Document qualities.js

---
 devel/js/main.js  |  11 ++---
 docs/qualities.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml        |   1 +
 3 files changed, 109 insertions(+), 5 deletions(-)
 create mode 100644 docs/qualities.md

diff --git a/devel/js/main.js b/devel/js/main.js
index 33d5a96..f08dcd7 100644
--- a/devel/js/main.js
+++ b/devel/js/main.js
@@ -179,12 +179,13 @@ situation('progress-bar', {
   qualities.create() to get a factory.
 */
 
-var DifficultyQuality = function (title, spec) {
-  undum.QualityDefinition.call(this, title, spec);
+var DifficultyQuality = function (title, threshold) {
+  undum.QualityDefinition.call(this, title);
+  this.threshold = threshold;
 };
 
 DifficultyQuality.prototype.format = function (character, value) {
-  if (value > 5) return "hard";
+  if (value > this.threshold) return "hard";
   return "easy";
 };
 
@@ -199,8 +200,8 @@ qualities({
   },
   settings: {
     name: 'Settings',
-    combatDifficulty: difficulty("Combat"),
-    puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles")
+    combatDifficulty: difficulty("Combat", 5),
+    puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles", 3)
   }
 });
 
diff --git a/docs/qualities.md b/docs/qualities.md
new file mode 100644
index 0000000..f5c6ada
--- /dev/null
+++ b/docs/qualities.md
@@ -0,0 +1,102 @@
+# qualities.js
+
+This module provides an interface for setting up quality definitions in Undum. Essentially it takes a single plain object, and builds definition and groups from that object, exposing an API where quality definitions are members of group objects.
+
+## Export
+
+## qualities(Object spec) -> null
+
+Creates the QualityDefinition and QualityGroup objects defined by the spec, and registers them in Undum. This is designed to be called only once from the story source file.
+
+The spec object follows this interface:
+
+```javascript
+{
+  quality_group: {
+    name: "Quality Group",
+    options: {},
+    quality1: QualityFactory("Name"),
+    quality2: QualityFactory("Name")
+  }
+}
+```
+
+Which is to say, it is a plain object; members of that plain object are quality groups. Each quality group object optionally supplies a `name` property and an `options` property. `name` is either a String (The title of the quality group, displayed as a heading in the game) or `null` (by default), indicating that no heading needs to be displayed. `options` is an options object for Undum's `QualityGroup` constructor; see Undum documentation.
+
+Each other property of a group object is taken as a quality. identifiers for qualities should be unique across the whole game, not merely across groups, because this structure will be "flattened" later. To create a quality using this API, you use a factory rather than one of Undum's supplied constructors directly.
+
+The following factories are provided as properties of `qualities`, and correspond to the following Undum constructors:
+
+|Factory          |Constructor             |
+|-----------------|------------------------|
+|`integer`        |`IntegerQuality`        |
+|`nonZeroInteger` |`NonZeroIntegerQuality` |
+|`numeric`        |`NumericQuality`        |
+|`fudgeAdjectives`|`FudgeAdjectivesQuality`|
+|`onOff`          |`OnOffQuality`          |
+|`yesNo`          |`YesNoQuality`          |
+|`wordScale`      |`WordScaleQuality`      |
+
+You can create your own factories by passing the constructor of a `QualityDefinition` implementation to `qualities.create()`. `qualities.use()` is a factory that takes a constructor as its first argument, and passes all other arguments on to that constructor, acting as a sort of shim.
+
+## Extended Example
+
+```javascript
+/* A QualityDefinition implementation constructor. */
+var DifficultyQuality = function (title, threshold) {
+  undum.QualityDefinition.call(this, title);
+  this.threshold = threshold;
+};
+
+DifficultyQuality.prototype.format = function (character, value) {
+  if (value > this.threshold) return "hard";
+  return "easy";
+};
+
+/* Create a factory to use in our definition spec. */
+var difficulty = qualities.create(DifficultyQuality);
+
+/* Give a specification of our quality definitions to the qualities()
+   function. */
+qualities({
+  stats: {
+    name: 'Statistics',
+    perception: qualities.integer("Perception"),
+    intelligence: qualities.integer("Intelligence"),
+    size: qualities.fudgeAdjectives("Size")
+  },
+  settings: {
+    name: 'Settings',
+    combatDifficulty: difficulty("Combat", 5), // Is equivalent to...
+    puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles", 3)
+  }
+});
+
+/* Remember that qualities have to have their initial value set in
+undum.game.init()*/
+```
+```coffeescript
+# A QualityDefinition implementation constructor.
+DifficultyQuality = (title, threshold) ->
+  undum.QualityDefinition.call(this, title)
+  this.threshold = threshold
+
+DifficultyQuality.prototype.format = (character, value) ->
+  if value > this.threshold then "hard" else "easy"
+
+# Create a factory to use in our definition spec.
+difficulty = qualities.create DifficultyQuality
+
+# Give a specification of our quality definitions to the qualities()
+# function.
+qualities
+  stats:
+    name: 'Statistics'
+    perception: qualities.integer("Perception")
+    intelligence: qualities.integer("Intelligence")
+    size: qualities.fudgeAdjectives("Size")
+  settings:
+    name: 'Settings'
+    combatDifficulty: difficulty("Combat", 5) # Is equivalent to...
+    puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles", 3)
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 7324151..8d69980 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -6,3 +6,4 @@ pages:
   - ['situation.md', 'API Documentation', 'situation.js']
   - ['elements.md', 'API Documentation', 'elements.js']
   - ['oneOf.md', 'API Documentation', 'oneOf.js']
+  - ['qualities.md', 'API Documentation', 'qualities.js']