diff --git a/scripts/adaptation.rb b/scripts/adaptation.rb
index 6d2e63017..50cf80a86 100644
--- a/scripts/adaptation.rb
+++ b/scripts/adaptation.rb
@@ -1,4 +1,4 @@
-# View or set level of cavern adaptation for the selected unit or the whole fort
+# View or set cavern adaptation levels
 # based on removebadthoughts.rb
 =begin
 
diff --git a/scripts/armoks-blessing.lua b/scripts/armoks-blessing.lua
index 0ae373c31..dfa99daad 100644
--- a/scripts/armoks-blessing.lua
+++ b/scripts/armoks-blessing.lua
@@ -1,7 +1,4 @@
--- Adjust all attributes, personality, age and skills of all dwarves in play
--- without arguments, all attributes, age & personalities are adjusted
--- arguments allow for skills to be adjusted as well
--- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY!
+-- Adjust all attributes of all dwarves to an ideal
 -- by vjek
 --[[=begin
 
@@ -12,6 +9,9 @@ Runs the equivalent of `rejuvenate`, `elevate-physical`, `elevate-mental`, and
 which sets every stat to an ideal - legendary skills, great traits, and
 easy-to-satisfy preferences.
 
+Without arguments, all attributes, age & personalities are adjusted.
+Arguments allow for skills to be adjusted as well.
+
 =end]]
 function rejuvenate(unit)
     if unit==nil then
diff --git a/scripts/autofarm.rb b/scripts/autofarm.rb
index ddfa7aae9..5dcd34679 100644
--- a/scripts/autofarm.rb
+++ b/scripts/autofarm.rb
@@ -1,4 +1,4 @@
-
+# Select cropt to plant based on current stocks
 =begin
 
 autofarm
diff --git a/scripts/autolabor-artisans.lua b/scripts/autolabor-artisans.lua
index 68b85817c..8a915243b 100644
--- a/scripts/autolabor-artisans.lua
+++ b/scripts/autolabor-artisans.lua
@@ -1,10 +1,14 @@
--- Executes an autolabor command for each labor where skill level influences output quality.
+-- Run an autolabor command for skill-affected labors.
 
 --[[=begin
 
 autolabor-artisans
 ==================
-Runs `autolabor`, with settings tuned for small but highly skilled workforces.
+Runs an `autolabor` command, for all labors where skill level
+influences output quality.  Examples::
+
+    autolabor-artisans 0 2 3
+    autolabor-artisans disable
 
 =end]]
 local artisan_labors = {
diff --git a/scripts/brainwash.lua b/scripts/brainwash.lua
index 1950323a8..b28f648f7 100644
--- a/scripts/brainwash.lua
+++ b/scripts/brainwash.lua
@@ -1,4 +1,4 @@
--- This script will brainwash a dwarf, modifying their personality
+-- Brainwash a dwarf, modifying their personality
 -- usage is:  target a unit in DF, and execute this script in dfhack
 -- by vjek
 --[[=begin
diff --git a/scripts/deterioratefood.rb b/scripts/deterioratefood.rb
index 729a9962f..c59171ea5 100644
--- a/scripts/deterioratefood.rb
+++ b/scripts/deterioratefood.rb
@@ -1,4 +1,4 @@
-# Make food and plants decay, and vanish after a few months
+# Food and plants decay, and vanish after a few months
 =begin
 
 deterioratefood
diff --git a/scripts/devel/inject-raws.lua b/scripts/devel/inject-raws.lua
index cea69eb61..048d4b560 100644
--- a/scripts/devel/inject-raws.lua
+++ b/scripts/devel/inject-raws.lua
@@ -1,4 +1,4 @@
--- Injects new reaction, item and building defs into the world.
+-- Inject new raw definitions into the world
 --[[=begin
 
 devel/inject-raws
@@ -9,6 +9,8 @@ This script attempts to inject new raw objects into your
 world. If the injected references do not match the actual
 edited raws, your save will refuse to load, or load but crash.
 
+This script can handle reaction, item and building definitions.
+
 The savegame contains a list of the relevant definition tokens in
 the right order, but all details are read from raws every time.
 This allows just adding stub definitions, and simply saving and
diff --git a/scripts/devel/inspect-screen.lua b/scripts/devel/inspect-screen.lua
index 9de6b2532..8f622756f 100644
--- a/scripts/devel/inspect-screen.lua
+++ b/scripts/devel/inspect-screen.lua
@@ -1,4 +1,4 @@
--- Read the tiles from the screen and display info about them.
+-- Read from the screen and display info about the tiles
 --[[=begin
 
 devel/inspect-screen
diff --git a/scripts/devel/list-filters.lua b/scripts/devel/list-filters.lua
index 5666315fc..7eb2210a9 100644
--- a/scripts/devel/list-filters.lua
+++ b/scripts/devel/list-filters.lua
@@ -1,4 +1,4 @@
--- List input items for the building currently being built.
+-- List input items for the building being built.
 --[[=begin
 
 devel/list-filters
diff --git a/scripts/devel/nuke-items.lua b/scripts/devel/nuke-items.lua
index d98901142..6b67f81c8 100644
--- a/scripts/devel/nuke-items.lua
+++ b/scripts/devel/nuke-items.lua
@@ -1,4 +1,4 @@
--- Deletes ALL items not held by units, buildings or jobs.
+-- Delete ALL items not held by units, buildings or jobs
 --[[=begin
 
 devel/nuke-items
diff --git a/scripts/devel/prepare-save.lua b/scripts/devel/prepare-save.lua
index dd1f81e45..c1e71ef7f 100644
--- a/scripts/devel/prepare-save.lua
+++ b/scripts/devel/prepare-save.lua
@@ -1,4 +1,4 @@
--- Prepare the current save for use with devel/find-offsets.
+-- Prepare the current save for devel/find-offsets
 --[[=begin
 
 devel/prepare-save
diff --git a/scripts/devel/scanitemother.rb b/scripts/devel/scanitemother.rb
index 1f130603f..1bdf58946 100644
--- a/scripts/devel/scanitemother.rb
+++ b/scripts/devel/scanitemother.rb
@@ -1,4 +1,4 @@
-# list indices in world.item.other[] where current selected item appears
+# list selected item's indices in world.item.other[]
 =begin
 
 devel/scanitemother
diff --git a/scripts/devel/spawn-unit-helper.rb b/scripts/devel/spawn-unit-helper.rb
index 437eb81db..77dadbcdd 100644
--- a/scripts/devel/spawn-unit-helper.rb
+++ b/scripts/devel/spawn-unit-helper.rb
@@ -1,4 +1,4 @@
-# setup stuff to allow arena creature spawn after a mode change
+# Allow arena creature spawn after a mode change
 
 df.world.arena_spawn.race.clear
 df.world.arena_spawn.caste.clear
diff --git a/scripts/devel/test-perlin.lua b/scripts/devel/test-perlin.lua
index 3b3a6a11a..ee8edc2ab 100644
--- a/scripts/devel/test-perlin.lua
+++ b/scripts/devel/test-perlin.lua
@@ -1,4 +1,4 @@
--- Generates an image using multiple octaves of perlin noise.
+-- Generates an image using perlin noise
 --[[=begin
 
 devel/test-perlin
diff --git a/scripts/digfort.rb b/scripts/digfort.rb
index 4ae48671e..d83928172 100644
--- a/scripts/digfort.rb
+++ b/scripts/digfort.rb
@@ -1,4 +1,4 @@
-# designate an area for digging according to a plan in csv format
+# designate an area based on a '.csv' plan
 =begin
 
 digfort
diff --git a/scripts/elevate-mental.lua b/scripts/elevate-mental.lua
index ed4b6b026..9db61ed79 100644
--- a/scripts/elevate-mental.lua
+++ b/scripts/elevate-mental.lua
@@ -1,4 +1,4 @@
--- This script will elevate all the mental attributes of a unit
+-- Elevate all the mental attributes of a unit
 -- by vjek
 --[[=begin
 
diff --git a/scripts/elevate-physical.lua b/scripts/elevate-physical.lua
index f425473d1..c210b4ffa 100644
--- a/scripts/elevate-physical.lua
+++ b/scripts/elevate-physical.lua
@@ -1,4 +1,4 @@
--- This script will elevate all the physical attributes of a unit
+-- Elevate all the physical attributes of a unit
 -- by vjek
 --[[=begin
 
diff --git a/scripts/fix/blood-del.lua b/scripts/fix/blood-del.lua
index 88d7d2756..ba32d4ab9 100644
--- a/scripts/fix/blood-del.lua
+++ b/scripts/fix/blood-del.lua
@@ -1,6 +1,5 @@
---makes it so that civs won't come with barrels full of blood, ichor, or goo
---author Urist Da Vinci
---edited by expwnent, scamtank
+-- Stop traders bringing blood, ichor, or goo
+--author Urist Da Vinci; edited by expwnent, scamtank
 --[[=begin
 
 fix/blood-del
diff --git a/scripts/fix/loyaltycascade.rb b/scripts/fix/loyaltycascade.rb
index 2cf52dd93..561e8b9e4 100644
--- a/scripts/fix/loyaltycascade.rb
+++ b/scripts/fix/loyaltycascade.rb
@@ -1,4 +1,4 @@
-# script to fix loyalty cascade, when you order your militia to kill friendly units
+# Cancels a 'loyalty cascade' when citizens are killed
 =begin
 
 fix/loyaltycascade
diff --git a/scripts/fix/population-cap.lua b/scripts/fix/population-cap.lua
index 483941982..1261fb504 100644
--- a/scripts/fix/population-cap.lua
+++ b/scripts/fix/population-cap.lua
@@ -1,4 +1,4 @@
--- Communicates current population to mountainhomes to avoid cap overshooting.
+-- Tells mountainhomes your pop. to avoid overshoot
 
 --[[=begin
 
diff --git a/scripts/gaydar.lua b/scripts/gaydar.lua
index 2dfa60730..66aec2c12 100644
--- a/scripts/gaydar.lua
+++ b/scripts/gaydar.lua
@@ -1,4 +1,4 @@
-local utils = require('utils')
+-- Shows the sexual orientation of units
 --[[=begin
 
 gaydar
@@ -8,6 +8,7 @@ the viability of livestock breeding programs.  Use ``gaydar -help`` for informat
 on available filters for orientation, citizenship, species, etc.
 
 =end]]
+local utils = require('utils')
 
 validArgs = utils.invert({
   'all',
diff --git a/scripts/growcrops.rb b/scripts/growcrops.rb
index 95bd7a81a..c3c143254 100644
--- a/scripts/growcrops.rb
+++ b/scripts/growcrops.rb
@@ -1,4 +1,4 @@
-# grow crops in farm plots. ex: growcrops helmet_plump 20
+# Instantly grow crops in farm plots
 =begin
 
 growcrops
diff --git a/scripts/gui/advfort_items.lua b/scripts/gui/advfort_items.lua
index 3727bf9a4..befb12ef5 100644
--- a/scripts/gui/advfort_items.lua
+++ b/scripts/gui/advfort_items.lua
@@ -1,4 +1,4 @@
-
+--Does something with items in adventure mode jobs
 --[[=begin
 
 gui/advfort_items
diff --git a/scripts/gui/assign-rack.lua b/scripts/gui/assign-rack.lua
index 3b18aa13e..575c09f94 100644
--- a/scripts/gui/assign-rack.lua
+++ b/scripts/gui/assign-rack.lua
@@ -1,5 +1,4 @@
--- Assign weapon racks to squads. Requires the weaponrack-unassign patch.
-
+-- Assign weapon racks to squads (needs binpatch)
 --[[=begin
 
 gui/assign-rack
diff --git a/scripts/gui/choose-weapons.lua b/scripts/gui/choose-weapons.lua
index f545e1d30..39e5fbf77 100644
--- a/scripts/gui/choose-weapons.lua
+++ b/scripts/gui/choose-weapons.lua
@@ -1,4 +1,4 @@
--- Rewrite individual choice weapons into specific types.
+-- Rewrite individual choice weapons to specific types
 --[[=begin
 
 gui/choose-weapons
diff --git a/scripts/gui/clone-uniform.lua b/scripts/gui/clone-uniform.lua
index 9893c3869..e6ae2fa8a 100644
--- a/scripts/gui/clone-uniform.lua
+++ b/scripts/gui/clone-uniform.lua
@@ -1,4 +1,4 @@
--- Clone the current uniform template in the military screen.
+-- Clone a uniform template in the military screen
 --[[=begin
 
 gui/clone-uniform
diff --git a/scripts/gui/companion-order.lua b/scripts/gui/companion-order.lua
index 9d901a4c9..60a141d0f 100644
--- a/scripts/gui/companion-order.lua
+++ b/scripts/gui/companion-order.lua
@@ -1,4 +1,4 @@
-
+-- Issue orders to companions in Adventure mode
 --[[=begin
 
 gui/companion-order
diff --git a/scripts/gui/gm-unit.lua b/scripts/gui/gm-unit.lua
index e25ebf944..3432882cb 100644
--- a/scripts/gui/gm-unit.lua
+++ b/scripts/gui/gm-unit.lua
@@ -1,4 +1,4 @@
--- Interface powered (somewhat user friendly) unit editor.
+-- Interface powered, user friendly, unit editor
 
 --[[=begin
 
diff --git a/scripts/gui/guide-path.lua b/scripts/gui/guide-path.lua
index aa77c9dea..be90ffb1c 100644
--- a/scripts/gui/guide-path.lua
+++ b/scripts/gui/guide-path.lua
@@ -1,4 +1,4 @@
--- Show and manipulate the path used by Guide Cart orders.
+-- Show/change the path used by Guide Cart orders
 --[[=begin
 
 gui/guide-path
diff --git a/scripts/hfs-pit.lua b/scripts/hfs-pit.lua
index c335ae2be..7fc571090 100644
--- a/scripts/hfs-pit.lua
+++ b/scripts/hfs-pit.lua
@@ -1,4 +1,4 @@
--- Creates a pit under the target leading straight to the Underworld.  Type '?' for help.
+-- Creates a pit to the Underworld under the target
 -- Based on script by IndigoFenix, @ https://gist.github.com/IndigoFenix/8776696
 --[[=begin
 
diff --git a/scripts/make-legendary.lua b/scripts/make-legendary.lua
index 6dfc78277..da29cd4c2 100644
--- a/scripts/make-legendary.lua
+++ b/scripts/make-legendary.lua
@@ -1,5 +1,4 @@
--- This script will modify a skill or the skills of a single unit
--- the skill will be increased to 20 (Legendary +5)
+-- Make a skill or skills of a unit Legendary +5
 -- by vjek
 --[[=begin
 
diff --git a/scripts/markdown.lua b/scripts/markdown.lua
index 8cd225573..14ecdaa2c 100644
--- a/scripts/markdown.lua
+++ b/scripts/markdown.lua
@@ -1,4 +1,4 @@
--- Save a copy of a text screen in markdown (for reddit among others). Use 'markdown help' for more details.
+-- Save a text screen in markdown (eg for reddit)
 -- This is a derivatiwe work based upon scripts/forum-dwarves.lua by Caldfir and expwnent
 -- Adapted for markdown by Mchl https://github.com/Mchl
 --[[=begin
diff --git a/scripts/migrants-now.lua b/scripts/migrants-now.lua
index b38e38115..aa9ad7b3f 100644
--- a/scripts/migrants-now.lua
+++ b/scripts/migrants-now.lua
@@ -1,4 +1,4 @@
--- Force a migrant wave (only works after hardcoded waves)
+-- Force a migrant wave (only after hardcoded waves)
 --[[=begin
 
 migrants-now
diff --git a/scripts/region-pops.lua b/scripts/region-pops.lua
index af4d36bde..935cd0f02 100644
--- a/scripts/region-pops.lua
+++ b/scripts/region-pops.lua
@@ -1,4 +1,4 @@
--- Shows populations of animals in the region, and allows tweaking them.
+-- Show or edit regional plant and animal populations
 --[[=begin
 
 region-pops
diff --git a/scripts/show-unit-syndromes.rb b/scripts/show-unit-syndromes.rb
index 70e72cba7..112b33474 100644
--- a/scripts/show-unit-syndromes.rb
+++ b/scripts/show-unit-syndromes.rb
@@ -1,6 +1,5 @@
-# Show syndromes affecting units and the remaining and maximum duration
-# original author: drayath
-# edited by expwnent
+# Show syndromes affecting units, including duration
+# original author: drayath, edited by expwnent
 =begin
 
 show-unit-syndromes
diff --git a/scripts/siren.lua b/scripts/siren.lua
index 053290a1c..5bf821141 100644
--- a/scripts/siren.lua
+++ b/scripts/siren.lua
@@ -1,4 +1,4 @@
--- Wakes up the sleeping, breaks up parties and stops breaks.
+-- Wakes up the sleeping, ends breaks and parties
 --[[=begin
 
 siren
diff --git a/scripts/source.rb b/scripts/source.rb
index 92f1a47a6..e9d7a64f3 100644
--- a/scripts/source.rb
+++ b/scripts/source.rb
@@ -1,4 +1,4 @@
-# create an infinite magma/water source/drain at the cursor
+# create an infinite source/drain of magma/water
 =begin
 
 source
diff --git a/scripts/starvingdead.rb b/scripts/starvingdead.rb
index 2e9e8f4a8..7ee985a7b 100644
--- a/scripts/starvingdead.rb
+++ b/scripts/starvingdead.rb
@@ -1,4 +1,4 @@
-# Make undead units weaken after one month, and vanish after six
+# Weaken and eventually destroy undead over time
 =begin
 
 starvingdead
diff --git a/scripts/warn-starving.lua b/scripts/warn-starving.lua
index abf95f9ec..12334bf99 100644
--- a/scripts/warn-starving.lua
+++ b/scripts/warn-starving.lua
@@ -1,4 +1,4 @@
--- Pauses the game with a warning if a creature is starving, dehydrated, or very drowsy.
+-- Pause and warn if a unit is starving
 -- By Meneth32, PeridexisErrant, Lethosor
 --@ module = true
 --[[=begin