Clean up some script docs (base + modtools)

acattaneo88 · Jul 3, 2020 · d265de7 · d265de7
1 parent e4b5898
commit d265de7
Show file tree

Hide file tree

Showing 31 changed files with 197 additions and 136 deletions.
diff --git a/adaptation.rb b/adaptation.rb
@@ -5,8 +5,12 @@
 adaptation
 ==========
 View or set level of cavern adaptation for the selected unit or the whole fort.
-Usage: ``adaptation <show|set> <him|all> [value]``.  The ``value`` must be
-between 0 and 800,000 inclusive.
+
+Usage::
+
+    adaptation <show|set> <him|all> [value]
+
+The ``value`` must be between 0 and 800,000 (inclusive).
 
 =end
 

diff --git a/add-thought.lua b/add-thought.lua
@@ -6,7 +6,7 @@
 add-thought
 ===========
 Adds a thought or emotion to the selected unit.  Can be used by other scripts,
-or the gui invoked by running ``add-thought gui`` with a unit selected.
+or the gui invoked by running ``add-thought -gui`` with a unit selected.
 
 ]====]
 

diff --git a/adv-fix-sleepers.lua b/adv-fix-sleepers.lua
@@ -4,12 +4,14 @@
 adv-fix-sleepers
 ================
 Fixes :bug:`6798`. This bug is characterized by sleeping units who refuse to
-    awaken in adventure mode regardless of talking to them, hitting them, or
-    waiting so long you die of thirst.
+awaken in adventure mode regardless of talking to them, hitting them, or waiting
+so long you die of thirst. If you come accross one or more bugged sleepers in
+adventure mode, simply run the script and all nearby sleepers will be cured.
+
+Usage::
+
+    adv-fix-sleepers
 
-Usage: If you come accross one or more bugged sleepers in adventure mode,
-    simply run the script (type adv-fix-sleepers into the dfhack console),
-    and all nearby sleepers will be cured.
 
 ]====]
 

diff --git a/assign-attributes.lua b/assign-attributes.lua
@@ -53,19 +53,19 @@ Usage:
                     are present, the unit attributes will be reset
                     and then the listed attributes will be modified.
 
-Example:
+Example::
 
-``assign-attributes -reset -attributes [ STRENGTH 2 AGILITY -1 SPATIAL_SENSE -1 ]``
-    This will reset all attributes to a neutral value and will set
-    the following values (if the currently selected unit is a dwarf):
+    assign-attributes -reset -attributes [ STRENGTH 2 AGILITY -1 SPATIAL_SENSE -1 ]
 
-     * Strength: a random value between 1750 and 1999 (tier 2);
-     * Agility: a random value between 401 and 650 (tier -1);
-     * Spatial sense: a random value between 1043 and 1292 (tier -1).
+This will reset all attributes to a neutral value and will set the following
+values (if the currently selected unit is a dwarf):
 
-    The final result will be:
-    ``She is very strong, but she is clumsy.
-    She has a questionable spatial sense.``
+ * Strength: a random value between 1750 and 1999 (tier 2);
+ * Agility: a random value between 401 and 650 (tier -1);
+ * Spatial sense: a random value between 1043 and 1292 (tier -1).
+
+The final result will be: "She is very strong, but she is clumsy.
+She has a questionable spatial sense."
 ]====]
 
 local utils = require("utils")

diff --git a/assign-beliefs.lua b/assign-beliefs.lua
@@ -48,24 +48,25 @@ Usage:
                     first all the unit beliefs will be reset and then those
                     beliefs listed after ``-beliefs`` will be modified.
 
-Example:
+Example::
 
-``assign-beliefs -reset -beliefs [ TRADITION 2 CRAFTSMANSHIP 3 POWER 0 CUNNING -1 ]``
-    Resets all the unit beliefs, then sets the listed
-    beliefs to the following values:
+    assign-beliefs -reset -beliefs [ TRADITION 2 CRAFTSMANSHIP 3 POWER 0 CUNNING -1 ]
 
-    * Tradition: a random value between 26 and 40 (level 2);
-    * Craftsmanship: a random value between 41 and 50 (level 3);
-    * Power: a random value between -10 and 10 (level 0);
-    * Cunning: a random value between -25 and -11 (level -1).
+Resets all the unit beliefs, then sets the listed beliefs to the following
+values:
 
-    The final result (for a dwarf) will be:
-    ``She personally is a firm believer in
-    the value of tradition and sees guile and
-    cunning as indirect and somewhat worthless.``
+* Tradition: a random value between 26 and 40 (level 2);
+* Craftsmanship: a random value between 41 and 50 (level 3);
+* Power: a random value between -10 and 10 (level 0);
+* Cunning: a random value between -25 and -11 (level -1).
+
+The final result (for a dwarf) will be: "She personally is a firm believer in
+the value of tradition and sees guile and cunning as indirect and somewhat
+worthless."
+
+Note that the beliefs aligned with the cultural values of the unit have not
+triggered a report.
 
-Note that the beliefs aligned with the cultural
-values of the unit have not triggered a report.
 ]====]
 
 local utils = require("utils")

diff --git a/assign-facets.lua b/assign-facets.lua
@@ -48,22 +48,22 @@ Usage:
                     first all the unit facets will be reset and then those
                     facets listed after ``-facets`` will be modified.
 
-Example:
+Example::
 
-``assign-facets -reset -facets [ HATE_PROPENSITY -2 CHEER_PROPENSITY -1 ]``
-    Resets all the unit facets, then sets the listed facets to the following values:
+    assign-facets -reset -facets [ HATE_PROPENSITY -2 CHEER_PROPENSITY -1 ]
 
-    * Hate propensity: a value between 10 and 24 (level -2);
-    * Cheer propensity: a value between 25 and 39 (level -1).
+Resets all the unit facets, then sets the listed facets to the following values:
 
-    The final result (for a dwarf) will be:
-    ``She very rarely develops negative feelings
-    toward things. She is rarely happy or enthusiastic,
-    and she is conflicted by this as she values
-    parties and merrymaking in the abstract.``
+* Hate propensity: a value between 10 and 24 (level -2);
+* Cheer propensity: a value between 25 and 39 (level -1).
+
+The final result (for a dwarf) will be: "She very rarely develops negative
+feelings toward things. She is rarely happy or enthusiastic, and she is
+conflicted by this as she values parties and merrymaking in the abstract."
+
+Note that the facets are compared to the beliefs, and if conflicts arise they
+will be reported.
 
-    Note that the facets are compared to the beliefs,
-    and if conflicts arise they will be reported.
 ]====]
 
 local utils = require("utils")

diff --git a/assign-goals.lua b/assign-goals.lua
@@ -41,12 +41,13 @@ Usage:
                     the unit goals will be erased and then those
                     goals listed after ``-goals`` will be added.
 
-Example:
+Example::
+
+    assign-goals -reset -goals [ MASTER_A_SKILL false ]
+
+Clears all the unit goals, then sets the "master a skill" goal. The final result
+will be: "dreams of mastering a skill".
 
-``assign-goals -reset -goals [ MASTER_A_SKILL false ]``
-    Clears all the unit goals, then sets the "master
-    a skill" goal. The final result will be:
-    ``dreams of mastering a skill.``
 ]====]
 
 local utils = require("utils")

diff --git a/assign-preferences.lua b/assign-preferences.lua
@@ -152,32 +152,42 @@ Usage:
 
 Examples:
 
-``assign-preferences -reset -likematerial [ INORGANIC:OBSIDAN PLANT:WILLOW:WOOD ]``
-    "likes alabaster and willow wood"
+* "likes alabaster and willow wood"::
 
-``assign-preferences -reset -likecreature SPARROW``
-    "likes sparrows for their ..."
+    assign-preferences -reset -likematerial [ INORGANIC:OBSIDAN PLANT:WILLOW:WOOD ]
 
-``assign-preferences -reset -likefood [ PLANT:MUSHROOM_HELMET_PLUMP:DRINK PLANT:OLIVE:FRUIT ]``
-    "prefers to consume dwarven wine and olives"
+* "likes sparrows for their ..."::
 
-``assign-preferences -reset -hatecreature SPIDER_JUMPING``
-    "absolutely detests jumping spiders
+    assign-preferences -reset -likecreature SPARROW
 
-``assign-preferences -reset -likeitem [ WOOD ITEM_WEAPON:ITEM_WEAPON_AXE_BATTLE ]``
-    "likes logs and battle axes"
+* "prefers to consume dwarven wine and olives"::
 
-``assign-preferences -reset -likeplant BERRIES_STRAW``
-    "likes straberry plants for their ..."
+    assign-preferences -reset -likefood [ PLANT:MUSHROOM_HELMET_PLUMP:DRINK PLANT:OLIVE:FRUIT ]
 
-``assign-preferences -reset -liketree OAK``
-    "likes oaks for their ..."
+* "absolutely detests jumping spiders::
 
-``assign-preferences -reset -likecolor AQUA``
-    "likes the color aqua"
+    assign-preferences -reset -hatecreature SPIDER_JUMPING
+
+* "likes logs and battle axes"::
+
+    assign-preferences -reset -likeitem [ WOOD ITEM_WEAPON:ITEM_WEAPON_AXE_BATTLE ]
+
+* "likes straberry plants for their ..."::
+
+    assign-preferences -reset -likeplant BERRIES_STRAW
+
+* "likes oaks for their ..."::
+
+    assign-preferences -reset -liketree OAK
+
+* "likes the color aqua"::
+
+    assign-preferences -reset -likecolor AQUA
+
+* "likes stars"::
+
+    assign-preferences -reset -likeshape STAR
 
-``assign-preferences -reset -likeshape STAR``
-    "likes stars"
 ]====]
 
 local utils = require("utils")

diff --git a/assign-profile.lua b/assign-profile.lua
@@ -50,22 +50,24 @@ Usage:
 
 Examples:
 
-``assign-profile -reset ALL``
-    Resets/clears all the characteristics of the
-    unit, leaving behind a very bland character.
-
-``assign-profile -profile CARPENTER -reset PROFILE``
-    Loads and applies the profile called "CARPENTER"
-    in the default json file, resetting/clearing
-    all the characteristics listed in the
-    profile, and then applying the new values.
-
-``assign-profile -file /hack/scripts/military_profiles.json -profile ARCHER -reset ATTRIBUTES``
-    Loads and applies the profile called "ARCHER"
-    in the provided json file, keeping all the old
-    characteristics but the attributes, which will
-    be reset (and then, if the profile provides some
-    attributes values, those value will be applied).
+* Resets/clears all the characteristics of the unit, leaving behind a very bland
+  character::
+
+    assign-profile -reset ALL
+
+* Loads and applies the profile called "CARPENTER" in the default json file,
+  resetting/clearing all the characteristics listed in the profile, and then
+  applying the new values::
+
+    assign-profile -profile CARPENTER -reset PROFILE
+
+* Loads and applies the profile called "ARCHER" in the provided json file,
+  keeping all the old characteristics but the attributes, which will be reset
+  (and then, if the profile provides some attributes values, those value will be
+  applied)::
+
+    assign-profile -file /hack/scripts/military_profiles.json -profile ARCHER -reset ATTRIBUTES
+
 ]====]
 
 local json = require "json"

diff --git a/assign-skills.lua b/assign-skills.lua
@@ -59,11 +59,13 @@ Usage:
                     first all the unit skills will be cleared
                     and then the listed skills will be added.
 
-Example:
+Example::
+
+    assign-skills -reset -skills [ WOODCUTTING 3 AXE 2 ]
+
+Clears all the unit skills, then adds the Wood cutter skill (competent level)
+and the Axeman skill (adequate level).
 
-``assign-skills -reset -skills [ WOODCUTTING 3 AXE 2 ]``
-    Clears all the unit skills, then adds the Wood cutter skill
-    (competent level) and the Axeman skill (adequate level).
 ]====]
 
 local utils = require("utils")

diff --git a/color-schemes.lua b/color-schemes.lua
@@ -22,8 +22,8 @@ Loaded as a module, this script will export those methods :
 
 For more information about arguments and return values, see ``hack/scripts/color-schemes.lua``.
 
-Notes :
-    * `gui/color-schemes` is the in-game GUI for that script.
+Related scripts:
+    * `gui/color-schemes` is the in-game GUI for this script.
     * `season-palette` swaps color schemes when the season changes.
 
 ]====]

diff --git a/deep-embark.lua b/deep-embark.lua
@@ -20,7 +20,8 @@ cause the script to run automatically and should hence
 be especially useful for modders who want their mod
 to include underground embarks by default.
 
-example:
+Example::
+
     deep-embark -depth CAVERN_2
 
 Usage::

diff --git a/deteriorateclothes.rb b/deteriorateclothes.rb
@@ -9,7 +9,9 @@
 and eventually just crumble into nothing. As warm and fuzzy as a dining
 room full of used socks makes your dwarves feel, your FPS does not like it.
 
-Usage: ``deteriorateclothes (start|stop)``
+Usage::
+
+    deteriorateclothes start|stop
 
 =end
 
@@ -78,4 +80,4 @@ def status
     else
         puts 'Not loaded.'
     end
-end
+end
diff --git a/deterioratecorpses.rb b/deterioratecorpses.rb
@@ -22,7 +22,9 @@
 This script causes all of those to rot away into nothing after
 several months.
 
-Usage: ``deterioratecorpses (start|stop)``
+Usage::
+
+    deterioratecorpses start|stop
 
 =end
 
@@ -103,4 +105,4 @@ def status
     else
         puts 'Not loaded.'
     end
-end
+end
diff --git a/deterioratefood.rb b/deterioratefood.rb
@@ -20,7 +20,9 @@
 helmets, just as many fish and meat. It gets pretty absurd. And your
 FPS doesn't like it.
 
-Usage: ``deterioratefood (start|stop)``
+Usage::
+
+    deterioratefood start|stop
 
 =end
 
@@ -93,4 +95,4 @@ def status
     else
         puts 'Not loaded.'
     end
-end
+end
diff --git a/dorf_tables.lua b/dorf_tables.lua
@@ -1,21 +1,19 @@
 -- dorf_tables has job distribution configurations, random number information for attributes generation, job configurations, profession configurations, dwarf types(ie. attributes/characteristic) configurations
--- usage: loaded by pimp-it.lua
+-- usage: loaded by dwarf-op.lua
 -- by josh cooper(cppcooper) [created: 12-2017 | last edited: 12-2018]
 --@ module = true
 
 local help = [====[
 
 dorf_tables
 ===========
-Data tables for pimp-it.lua.
-
-Usage: load inside secondary script (pimp-it.lua)
+Data tables for `dwarf-op` - not intended to be called directly
 
 ]====]
 
 if not moduleMode then
     print("scripts/dorf_tables.lua is a content library; calling it does nothing.")
-    do return end
+    return
 end
 print("Loading data tables..")