From d44cc1716190c22b993fb882934e313b5938f696 Mon Sep 17 00:00:00 2001
From: John Benediktsson <mrjbq7@gmail.com>
Date: Sat, 24 Aug 2013 11:39:31 -0700
Subject: [PATCH] update docs for help.lint checks.

---
 basis/documents/elements/elements-docs.factor |  4 ++--
 basis/game/input/input-docs.factor            |  4 ++--
 basis/http/client/client-docs.factor          |  2 +-
 basis/ui/gadgets/worlds/worlds-docs.factor    | 22 ++++++++---------
 .../pixel-formats/pixel-formats-docs.factor   | 24 +++++++++----------
 basis/unix/users/users-docs.factor            |  2 +-
 core/classes/classes-docs.factor              |  4 +++-
 core/generic/generic-docs.factor              |  9 +++----
 core/source-files/source-files-docs.factor    | 15 ++++++------
 core/vocabs/vocabs-docs.factor                |  4 +++-
 core/words/words-docs.factor                  |  4 +++-
 extra/game/models/util/util-docs.factor       |  4 ++--
 extra/game/models/util/util.factor            |  2 +-
 extra/graphviz/builder/builder-docs.factor    |  2 +-
 extra/graphviz/graphviz-docs.factor           |  4 ++--
 15 files changed, 57 insertions(+), 49 deletions(-)

diff --git a/basis/documents/elements/elements-docs.factor b/basis/documents/elements/elements-docs.factor
index 6a3f57c15a..90c4a5f9e3 100644
--- a/basis/documents/elements/elements-docs.factor
+++ b/basis/documents/elements/elements-docs.factor
@@ -28,7 +28,7 @@ HELP: one-line-elt
 { one-line-elt line-elt } related-words
 
 HELP: line-elt
-{ $class-description "An element representing a single line. The " { $link prev-elt } " and " { $link next-elt } " words return the location of the previous and next line from the current location." } ;
+{ $description "An element representing a single line. The " { $link prev-elt } " and " { $link next-elt } " words return the location of the previous and next line from the current location." } ;
 
 HELP: doc-elt
 { $class-description "An element representing the entire document. The " { $link prev-elt } " word outputs the start of the document and the " { $link next-elt } " word outputs the end of the document." } ;
@@ -51,4 +51,4 @@ $nl
     next-elt
 } ;
 
-ABOUT: "documents.elements"
\ No newline at end of file
+ABOUT: "documents.elements"
diff --git a/basis/game/input/input-docs.factor b/basis/game/input/input-docs.factor
index 1ea5dcc650..078721937f 100644
--- a/basis/game/input/input-docs.factor
+++ b/basis/game/input/input-docs.factor
@@ -176,10 +176,10 @@ HELP: buttons-delta-as
 { button-delta buttons-delta buttons-delta-as } related-words
 
 HELP: pressed
-{ $class-description "This symbol is returned by " { $link button-delta } " or " { $link buttons-delta } " to represent a button or key being pressed between two samples of its state." } ;
+{ $description "This symbol is returned by " { $link button-delta } " or " { $link buttons-delta } " to represent a button or key being pressed between two samples of its state." } ;
 
 HELP: released
-{ $class-description "This symbol is returned by " { $link button-delta } " or " { $link buttons-delta } " to represent a button or key being released between two samples of its state." } ;
+{ $description "This symbol is returned by " { $link button-delta } " or " { $link buttons-delta } " to represent a button or key being released between two samples of its state." } ;
 
 { pressed released } related-words
 
diff --git a/basis/http/client/client-docs.factor b/basis/http/client/client-docs.factor
index 437f595deb..89c05f1fe7 100644
--- a/basis/http/client/client-docs.factor
+++ b/basis/http/client/client-docs.factor
@@ -5,7 +5,7 @@ http.client.post-data.private io.encodings.8-bit.latin1 ;
 IN: http.client
 
 HELP: download-failed
-{ $error-description "Thrown by " { $link http-request } " if the server returns a status code other than 200. The " { $slot "response" } " and " { $slot "body" } " slots can be inspected for the underlying cause of the problem." } ;
+{ $error-description "Thrown by " { $link http-request } " if the server returns a status code other than 200. The " { $slot "response" } " slot can be inspected for the underlying cause of the problem." } ;
 
 HELP: too-many-redirects
 { $error-description "Thrown by " { $link http-request } " if the server returns a chain of than " { $link max-redirects } " redirections." } ;
diff --git a/basis/ui/gadgets/worlds/worlds-docs.factor b/basis/ui/gadgets/worlds/worlds-docs.factor
index 3dc03aa4ec..ccb651ad30 100644
--- a/basis/ui/gadgets/worlds/worlds-docs.factor
+++ b/basis/ui/gadgets/worlds/worlds-docs.factor
@@ -48,17 +48,17 @@ HELP: focus-path
 HELP: world
 { $class-description "A gadget which appears at the top of the gadget hieararchy, and in turn may be displayed in a native window. Worlds have the following slots:"
     { $list
-        { { $snippet "active?" } " - if set to " { $link f } ", the world will not be drawn. This slot is set to " { $link f } " if an error is thrown while drawing the world; this prevents multiple debugger windows from being shown." }
-        { { $snippet "layers" } " - a sequence of glass panes in front of the primary gadget, used to implement behaviors such as popup menus which are hidden when the mouse is clicked outside the menu. See " { $link "ui.gadgets.glass" } "." }
-        { { $snippet "title" } " - a string to be displayed in the title bar of the native window containing the world." }
-        { { $snippet "status" } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
-        { { $snippet "status-owner" } " - the gadget that displayed the most recent status message." }
-        { { $snippet "focus" } " - the current owner of the keyboard focus in the world." }
-        { { $snippet "focused?" } " - a boolean indicating if the native window containing the world has keyboard focus." }
-        { { $snippet "grab-input?" } " - if set to " { $link t } ", the world will hide the mouse cursor and disable normal mouse input while focused. Use " { $link grab-input } " and " { $link ungrab-input } " to change this setting." }
-        { { $snippet "handle" } " - a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
-        { { $snippet "window-loc" } " - the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
-        { { $snippet "window-controls" } " - the set of " { $link "ui.gadgets.worlds-window-controls" } " with which the world window was created." }
+        { { $slot "active?" } " - if set to " { $link f } ", the world will not be drawn. This slot is set to " { $link f } " if an error is thrown while drawing the world; this prevents multiple debugger windows from being shown." }
+        { { $slot "layers" } " - a sequence of glass panes in front of the primary gadget, used to implement behaviors such as popup menus which are hidden when the mouse is clicked outside the menu. See " { $link "ui.gadgets.glass" } "." }
+        { { $slot "title" } " - a string to be displayed in the title bar of the native window containing the world." }
+        { { $slot "status" } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
+        { { $slot "status-owner" } " - the gadget that displayed the most recent status message." }
+        { { $slot "focus" } " - the current owner of the keyboard focus in the world." }
+        { { $slot "focused?" } " - a boolean indicating if the native window containing the world has keyboard focus." }
+        { { $slot "grab-input?" } " - if set to " { $link t } ", the world will hide the mouse cursor and disable normal mouse input while focused. Use " { $link grab-input } " and " { $link ungrab-input } " to change this setting." }
+        { { $slot "handle" } " - a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
+        { { $slot "window-loc" } " - the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
+        { { $slot "window-controls" } " - the set of " { $link "ui.gadgets.worlds-window-controls" } " with which the world window was created." }
     }
 } ;
 
diff --git a/basis/ui/pixel-formats/pixel-formats-docs.factor b/basis/ui/pixel-formats/pixel-formats-docs.factor
index 6537f34727..9309085676 100644
--- a/basis/ui/pixel-formats/pixel-formats-docs.factor
+++ b/basis/ui/pixel-formats/pixel-formats-docs.factor
@@ -66,45 +66,45 @@ M: picky-depth-buffered-world check-world-pixel-format
 ;
 
 HELP: double-buffered
-{ $class-description "Requests a double-buffered pixel format." } ;
+{ $description "Requests a double-buffered pixel format." } ;
 HELP: stereo
-{ $class-description "Requests a stereoscopic pixel format." } ;
+{ $description "Requests a stereoscopic pixel format." } ;
 
 HELP: offscreen
-{ $class-description "Requests a pixel format suitable for offscreen rendering." } ;
+{ $description "Requests a pixel format suitable for offscreen rendering." } ;
 HELP: fullscreen
-{ $class-description "Requests a pixel format suitable for fullscreen rendering." }
+{ $description "Requests a pixel format suitable for fullscreen rendering." }
 { $notes "On some window systems this is not distinct from " { $link windowed } "." } ;
 HELP: windowed
-{ $class-description "Requests a pixel format suitable for rendering to a window." } ;
+{ $description "Requests a pixel format suitable for rendering to a window." } ;
 
 { offscreen fullscreen windowed } related-words
 
 HELP: accelerated
-{ $class-description "Requests a pixel format supported by GPU hardware acceleration." } ;
+{ $description "Requests a pixel format supported by GPU hardware acceleration." } ;
 HELP: software-rendered
-{ $class-description "Requests a pixel format only supported by the window system's default software renderer." } ;
+{ $description "Requests a pixel format only supported by the window system's default software renderer." } ;
 
 { accelerated software-rendered } related-words
 
 HELP: backing-store
-{ $class-description "Used with " { $link double-buffered } " to request a double-buffered pixel format where the back buffer contents are preserved and copied to the front when buffers are swapped." } ;
+{ $description "Used with " { $link double-buffered } " to request a double-buffered pixel format where the back buffer contents are preserved and copied to the front when buffers are swapped." } ;
 
 { double-buffered backing-store } related-words
 
 HELP: multisampled
-{ $class-description "Requests a pixel format with multisampled antialiasing enabled. The " { $link sample-buffers } " and " { $link samples } " attributes must also be provided to specify the level of multisampling." }
+{ $description "Requests a pixel format with multisampled antialiasing enabled. The " { $link sample-buffers } " and " { $link samples } " attributes must also be provided to specify the level of multisampling." }
 { $notes "On some window systems this is not distinct from " { $link supersampled } "." } ;
 
 HELP: supersampled
-{ $class-description "Requests a pixel format with supersampled antialiasing enabled. The " { $link sample-buffers } " and " { $link samples } " attributes must also be provided to specify the level of supersampling." }
+{ $description "Requests a pixel format with supersampled antialiasing enabled. The " { $link sample-buffers } " and " { $link samples } " attributes must also be provided to specify the level of supersampling." }
 { $notes "On some window systems this is not distinct from " { $link multisampled } "." } ;
 
 HELP: sample-alpha
-{ $class-description "Used with " { $link multisampled } " or " { $link supersampled } " to request more accurate multisampling of alpha values." } ;
+{ $description "Used with " { $link multisampled } " or " { $link supersampled } " to request more accurate multisampling of alpha values." } ;
 
 HELP: color-float
-{ $class-description "Requests a pixel format where the color buffer is stored in floating-point format." } ;
+{ $description "Requests a pixel format where the color buffer is stored in floating-point format." } ;
 
 HELP: color-bits
 { $class-description "Requests a pixel format with a color buffer of at least " { $snippet "value" } " bits per pixel." } ;
diff --git a/basis/unix/users/users-docs.factor b/basis/unix/users/users-docs.factor
index fe0c3e853d..af9a88941c 100644
--- a/basis/unix/users/users-docs.factor
+++ b/basis/unix/users/users-docs.factor
@@ -20,7 +20,7 @@ HELP: new-passwd
 { $description "Creates a new passwd tuple dependent on the operating system." } ;
 
 HELP: passwd
-{ $description "A platform-specific tuple corresponding to every field from the Unix passwd struct. BSD passwd structures have four extra slots: " { $slot "change" } ", " { $slot "class" } ", " { $slot "expire" } ", " { $slot "fields" } "." } ;
+{ $description "A platform-specific tuple corresponding to every field from the Unix passwd struct. BSD passwd structures have four extra slots: " { $snippet "change" } ", " { $snippet "class" } ", " { $snippet "expire" } ", " { $snippet "fields" } "." } ;
 
 HELP: user-cache
 { $description "A symbol storing passwd structures indexed by user-ids when within a " { $link with-user-cache } "." } ;
diff --git a/core/classes/classes-docs.factor b/core/classes/classes-docs.factor
index 965fcdc3ae..ec118be4aa 100644
--- a/core/classes/classes-docs.factor
+++ b/core/classes/classes-docs.factor
@@ -71,10 +71,12 @@ $nl
 
 ABOUT: "classes"
 
+HELP: class
+{ $class-description "The class of all class words." } ;
+
 HELP: class-of
 { $values { "object" object } { "class" class } }
 { $description "Outputs an object's canonical class. While an object may be an instance of more than one class, the canonical class is either its built-in class, or if the object is a tuple, its tuple class." }
-{ $class-description "The class of all class words." }
 { $examples { $example "USING: classes prettyprint ;" "1.0 class-of ." "float" } { $example "USING: classes prettyprint ;" "IN: scratchpad" "TUPLE: point x y z ;\nT{ point f 1 2 3 } class-of ." "point" } } ;
 
 HELP: classes
diff --git a/core/generic/generic-docs.factor b/core/generic/generic-docs.factor
index 9af2805313..2cdd7b5431 100644
--- a/core/generic/generic-docs.factor
+++ b/core/generic/generic-docs.factor
@@ -128,19 +128,20 @@ HELP: define-generic
 
 HELP: M\
 { $syntax "M\\ class generic" }
-{ $class-description "Pushes a method on the stack." }
+{ $description "Pushes a method on the stack." }
 { $examples { $code "M\\ fixnum + see" } { $code "USING: ui.gadgets.editors ui.render ;" "M\\ editor draw-gadget* edit" } } ;
 
+HELP: method
+{ $class-description "The class of method bodies, which are words with special word properties set." } ;
+
 HELP: lookup-method
 { $values { "class" class } { "generic" generic } { "method" method } }
 { $description "Looks up a method definition." }
-{ $class-description "The class of method bodies, which are words with special word properties set." }
 { $errors "Throws an error if the method does not exist." } ;
 
 HELP: ?lookup-method
 { $values { "class" class } { "generic" generic } { "method/f" { $maybe method } } }
-{ $description "Looks up a method definition." }
-{ $class-description "The class of method bodies, which are words with special word properties set." } ;
+{ $description "Looks up a method definition." } ;
 
 { lookup-method ?lookup-method create-method POSTPONE: M: } related-words
 
diff --git a/core/source-files/source-files-docs.factor b/core/source-files/source-files-docs.factor
index fc99b7afd1..9668abdfce 100644
--- a/core/source-files/source-files-docs.factor
+++ b/core/source-files/source-files-docs.factor
@@ -23,17 +23,18 @@ $nl
 ABOUT: "source-files"
 
 HELP: source-files
-{ $var-description "An assoc mapping pathname strings to " { $link source-file } " instances, representing loaded source files." } ;
+{ $var-description "An assoc mapping pathname strings to " { $link source-file-tuple } " instances, representing loaded source files." } ;
 
 HELP: source-file
-{ $values { "path" "a pathname string" } { "source-file" source-file } }
-{ $description "Outputs the source file associated to a path name, creating the source file first if it doesn't exist. Source files are retained in the " { $link source-files } " variable." }
+{ $values { "path" "a pathname string" } { "source-file" source-file-tuple } }
+{ $description "Outputs the source file associated to a path name, creating the source file first if it doesn't exist. Source files are retained in the " { $link source-files } " variable." } ;
+
+HELP: source-file-tuple
 { $class-description "Instances retain information about loaded source files, and have the following slots:"
     { $list
-        { { $snippet "path" } " - a pathname string." }
-        { { $snippet "checksum" } " - the CRC32 checksum of the source file's contents at the time it was most recently loaded." }
-        { { $snippet "uses" } " - an assoc whose keys are words referenced from this source file's top level form." }
-        { { $snippet "definitions" } " - a pair of assocs, containing definitions and classes defined in this source file, respectively" }
+        { { $slot "path" } " - a pathname string." }
+        { { $slot "checksum" } " - the CRC32 checksum of the source file's contents at the time it was most recently loaded." }
+        { { $slot "definitions" } " - a pair of assocs, containing definitions and classes defined in this source file, respectively" }
     }
 } ;
 
diff --git a/core/vocabs/vocabs-docs.factor b/core/vocabs/vocabs-docs.factor
index 64101dc6d6..6d37f3bed1 100644
--- a/core/vocabs/vocabs-docs.factor
+++ b/core/vocabs/vocabs-docs.factor
@@ -53,7 +53,9 @@ HELP: vocabs
 
 HELP: lookup-vocab
 { $values { "vocab-spec" "a vocabulary specifier" } { "vocab" vocab } }
-{ $description "Outputs a named vocabulary, or " { $link f } " if no vocabulary with this name exists." }
+{ $description "Outputs a named vocabulary, or " { $link f } " if no vocabulary with this name exists." } ;
+
+HELP: vocab
 { $class-description "Instances represent vocabularies." } ;
 
 HELP: vocab-name
diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor
index 3f5dca6d2e..72320d23b6 100644
--- a/core/words/words-docs.factor
+++ b/core/words/words-docs.factor
@@ -270,7 +270,9 @@ HELP: bootstrapping?
 
 HELP: last-word
 { $values { "word" word } }
-{ $description "Outputs the most recently defined word." }
+{ $description "Outputs the most recently defined word." } ;
+
+HELP: word
 { $class-description "The class of words. One notable subclass is " { $link class } ", the class of class words." } ;
 
 { last-word set-last-word save-location } related-words
diff --git a/extra/game/models/util/util-docs.factor b/extra/game/models/util/util-docs.factor
index e38836cec7..77e198d18e 100644
--- a/extra/game/models/util/util-docs.factor
+++ b/extra/game/models/util/util-docs.factor
@@ -9,5 +9,5 @@ HELP: indexed-seq
 { $class-description "A sequence described by a sequence of unique elements and a sequence of indices. The sequence can only be appended to. An associative map is used as a reverse lookup table when appending." } ;
 
 HELP: <indexed-seq>
-{ $values { "dseq-exemplar" sequence } { "iseq-examplar" sequence } { "rassoc-examplar" assoc } }
-{ $class-description "Construct an " { $link indexed-seq } " using the given examplars for the underlying data structures." } ;
+{ $values { "dseq-exemplar" sequence } { "iseq-exemplar" sequence } { "rassoc-exemplar" assoc } { "indexed-seq" indexed-seq } }
+{ $description "Construct an " { $link indexed-seq } " using the given exemplars for the underlying data structures." } ;
diff --git a/extra/game/models/util/util.factor b/extra/game/models/util/util.factor
index 4726122e1a..de25ad4a1a 100644
--- a/extra/game/models/util/util.factor
+++ b/extra/game/models/util/util.factor
@@ -28,7 +28,7 @@ M:: indexed-seq set-nth ( elt n seq -- )
         elt dseq push
     ] if* ; inline
 
-: <indexed-seq> ( dseq-examplar iseq-exampler rassoc-examplar -- indexed-seq )
+: <indexed-seq> ( dseq-exemplar iseq-exemplar rassoc-exemplar -- indexed-seq )
     indexed-seq new
     swap clone >>rassoc
     swap clone >>iseq
diff --git a/extra/graphviz/builder/builder-docs.factor b/extra/graphviz/builder/builder-docs.factor
index df071fef61..a98ff43ae9 100644
--- a/extra/graphviz/builder/builder-docs.factor
+++ b/extra/graphviz/builder/builder-docs.factor
@@ -22,7 +22,7 @@ HELP: improper-statement-error
 { $values
     { "obj" object }
 }
-{ $error-description "Thrown if, in a call to " { $link build-alien } ", any of a " { $link graph } "'s " { $slot "statements" } " is not an instance of:" { $list { $link subgraph } { $link node } { $link edge } { $link graph-attributes } { $link node-attributes } { $link edge-attributes } } }
+{ $error-description "Thrown if, in a call to " { $link build-alien } ", any of a " { $link graph } "'s " { $snippet "statements" } " is not an instance of:" { $list { $link subgraph } { $link node } { $link edge } { $link graph-attributes } { $link node-attributes } { $link edge-attributes } } }
 ;
 
 HELP: non-graph-error
diff --git a/extra/graphviz/graphviz-docs.factor b/extra/graphviz/graphviz-docs.factor
index 19c7a49dfa..2467dc789b 100644
--- a/extra/graphviz/graphviz-docs.factor
+++ b/extra/graphviz/graphviz-docs.factor
@@ -483,7 +483,7 @@ HELP: edge
 { $class-description
 "Represents a Graphviz edge. Each " { $link edge } " is defined by its " { $slot "tail" } " slot and its " { $slot "head" } " slot. Each slot must be either"
 { $list
-    { { $instance string } " representing the " { $slot "id" } " of a " { $link node } " or" }
+    { { $instance string } " representing the " { $snippet "id" } " of a " { $link node } " or" }
     { { $instance subgraph } ", which is a convenient way to represent multiple Graphviz edges." }
 }
 
@@ -567,7 +567,7 @@ HELP: subgraph
 { $class-description
 "Represents a logical grouping of nodes and edges within a Graphviz graph. See " { $url "http://graphviz.org/Documentation.php" } " for more information."
 $nl
-"Its structure is largely similar to " { $link graph } ", except " { $link subgraph } " only has two slots: " { $slot "id" } " (" { $instance string } ") and " { $slot "statements" } " (" { $instance sequence } "). The " { $slot "strict?" } " and " { $slot "directed?" } " slots of the parent " { $link graph } " are implicitly inherited by a " { $link subgraph } "."
+"Its structure is largely similar to " { $link graph } ", except " { $link subgraph } " only has two slots: " { $slot "id" } " (" { $instance string } ") and " { $slot "statements" } " (" { $instance sequence } "). The " { $snippet "strict?" } " and " { $snippet "directed?" } " slots of the parent " { $link graph } " are implicitly inherited by a " { $link subgraph } "."
 $nl
 { $slot "id" } " and " { $slot "statements" } " correspond to the name and defining \"body\" of a subgraph in the DOT language, as in " { $strong "subgraph" } " " { $slot "id" } " " { $strong "{" } " ... " { $slot "statements" } " ... " { $strong "}" } "."
 $nl
-- 
2.34.1