Documentation changes

docs/elements.md

@@ -77,23 +77,23 @@ Every ElementHelper object supplies the following methods. All of them return a
 
 Returns a new ElementHelper with the given string as its `_alt` property. This property is used as the element's `alt` attribute.
 
-## class :: String -> ElementHelper
+## class(className) -> ElementHelper
 
 Returns a new ElementHelper with the given String as an additional class. This method is *additive,* so it adds new classes to the element. To completely change the element's classes, use ElementHelper#Classes
 
-## classes :: Array -> ElementHelper
+## classes(classes) -> ElementHelper
 
 Returns a new ElementHelper with the given Array as a list of classes. This shadows any previously defined classes. If you wanted to erase all of an element's classes, you could use `element.classes([])`.
 
-## content :: String -> ElementHelper
+## content(content) -> ElementHelper
 
 Returns a new ElementHelper with the given content. "Content" here means the element's inner html, which will be parsed as inline markdown.
 
-## id :: String -> ElementHelper
+## id(idName) -> ElementHelper
 
 Returns a new ElementHelper with the given id. This string is then used as the value of the element's `id` attribute.
 
-## ref :: String -> ElementHelper
+## ref(url) -> ElementHelper
 
 Returns a new ElementHelper with the given string as its `_ref` property. This property is used as the value of the element's `href` attribute.
 
@@ -101,15 +101,15 @@ Returns a new ElementHelper with the given string as its `_ref` property. This p
 
 Returns a new ElementHelper with the given string as its `_src` property. This property is used as the value of the element's `src` attribute.
 
-## url :: String -> ElementHelper, situation :: String -> ElementHelper
+## url(url) -> ElementHelper, situation(url) -> ElementHelper
 
-Aliases for `ElementHelper#ref`, for code legibility.
+Aliases for `ElementHelper#ref`, for legibility.
 
-## once
+## once() -> ElementHelper
 
 Returns a new ElementHelper with the `once` class added to it. This class has special meaning to Undum (once links stop being hyperlinks once clicked on). This method is shorthand for `class('once')`.
 
-## type :: String -> ElementHelper
+## type(linkType) -> ElementHelper
 
 Returns a new ElementHelper with its `_linkType` property set to the given string. This property is used to integrate with Raconteur's special link types. When the ElementHelper is stringified, the `_linkType` property is added as a class to the link, and as a prefix to its href. So a link with a type of "writer" and a ref of "foo" will be written out with `href="./_writer_foo"`; when clicked, Raconteur will look for the current situation's `writers.foo` property.
 
@@ -117,7 +117,7 @@ If an ElementHelper's type is `action`, it will prefix the link's ref with `./`
 
 It's possible to clear an element's `_linkType_` property by setting it to `null` or an empty string: `element.type(null)`.
 
-## writer, replacer, inserter, action
+## writer(), replacer(), inserter(), action() -> ElementHelper
 
 All of those methods are shorthand for defining an ElementHelper for an action link.
 
@@ -148,6 +148,12 @@ Returns a new `<img>` elementHelper object, with its alt text set to the argumen
 
 Returns a new elementHelper object for the given tag. Usually, this can be called once to define your own custom element helpers:
 
+```coffeescript
+elements = require('raconteur/elements.js')
+em = elements.element('em')
+glow = (content) -> em.class('glow').content(content)
+```
+
 ```javascript
 var elements = require('raconteur/elements.js');
 var em = elements.element('em');

docs/qualities.md

@@ -41,6 +41,32 @@ You can create your own factories by passing the constructor of a `QualityDefini
 
 ## Extended Example
 
+```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)
+```
+
 ```javascript
 /* A QualityDefinition implementation constructor. */
 var DifficultyQuality = function (title, threshold) {
@@ -75,28 +101,3 @@ qualities({
 /* 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)
-```

docs/situation.md

@@ -21,13 +21,13 @@ var situation = require('raconteur/situation.js');
 
 `situation()` is the root export of this module, and the only directly exposed method. It takes a name for the situation and an object specification, and then builds a RaconteurSituation object *and adds it to undum.game.situations.* This is not a true constructor, but rather a function that adds a situation to your game according to a given specification.
 
-### name :: String
+### name
 
-The situation's canonical name, equivalent to `undum.Situation#name`. This name is used to refer to the situation in other situations, in their `choices` property, for example, or in direct links.
+The situation's canonical name, equivalent to `undum.Situation#name`. This string identifier is used to refer to the situation in other situations, in their `choices` property, for example, or in direct links.
 
 Name strings should only contain valid URL characters. It's recommended that they contain no spaces or punctuation other than `_`.
 
-### spec :: Object
+### spec
 
 An object describing the situation to be created. Every own property of this object will be added to the situation object created, allowing you to add arbitrary properties for your own purposes.
 
@@ -59,7 +59,7 @@ The return value from those functions is discarded. They're intended to be used
 
 ### choices :: Array
 
-A list of situation names and/or tags, used by Undum to construct a list of choices for a situation. This list of choices is the last thing outputted when a situation is entered, after `after()` is called.
+A list of situation names and/or tags, used by Undum to construct a list of choices for a situation. Tags should be prefixed with `#`. This list of choices is the last thing outputted when a situation is entered, after `after()` is called.
 
 ### content :: String or Function
 
@@ -127,7 +127,7 @@ This is a fenced code block.
 
 ### tags :: Array (from undum.Situation)
 
-A list of tags. See Undum documentation.
+A list of tags, without a leading `#`. In a situation's `choices` list, other situations can be referred specifically by name, or in groups by tag.
 
 ### optionText :: String (from undum.Situation)