More documentation fixes

extra/concurrency/distributed/distributed-docs.factor

@@ -2,9 +2,7 @@ USING: help.markup help.syntax concurrency.messaging threads ;
 IN: concurrency.distributed
 
 HELP: local-node
-{ $values { "addrspec" "an address specifier" } 
-}
-{ $description "Return the node the current thread is running on." } ;
+{ $var-description "A variable containing the node the current thread is running on." } ;
 
 HELP: start-node
 { $values { "port" "a port number between 0 and 65535" } }

extra/concurrency/distributed/distributed.factor

@@ -6,7 +6,7 @@ namespaces kernel io.encodings.binary ;
 QUALIFIED: io.sockets
 IN: concurrency.distributed
 
-SYMBOL: local-node ( -- addrspec )
+SYMBOL: local-node
 
 : handle-node-client ( -- )
     deserialize first2 get-process send ;

extra/farkup/farkup-docs.factor

@@ -1,6 +1,6 @@
 USING: help.markup help.syntax ;
 IN: farkup
 
-HELP: parse-farkup
+HELP: convert-farkup
 { $values { "string" "a string" } { "string'" "a string" } }
 { $description "Parse a string as farkup (Factor mARKUP) and output the result aas an string of HTML." } ;

extra/help/lint/lint.factor

@@ -5,7 +5,7 @@ words strings classes tools.browser namespaces io
 io.streams.string prettyprint definitions arrays vectors
 combinators splitting debugger hashtables sorting effects vocabs
 vocabs.loader assocs editors continuations classes.predicate
-macros combinators.lib sequences.lib ;
+macros combinators.lib sequences.lib math ;
 IN: help.lint
 
 : check-example ( element -- )
@@ -27,8 +27,13 @@ IN: help.lint
     ] unless ;
 
 : effect-values ( word -- seq )
-    stack-effect dup effect-in swap effect-out
-    append [ string? ] subset prune natural-sort ;
+    stack-effect dup effect-in swap effect-out append [
+        {
+            { [ dup word? ] [ word-name ] }
+            { [ dup integer? ] [ drop "object" ] }
+            { [ dup string? ] [ ] }
+        } cond
+    ] map prune natural-sort ;
 
 : contains-funky-elements? ( element -- ? )
     {

extra/io/server/server-docs.factor

@@ -2,7 +2,7 @@ USING: help help.syntax help.markup io ;
 IN: io.server
 
 HELP: with-server
-{ $values { "seq" "a sequence of address specifiers" } { "service" "a string or " { $link f } } { "quot" "a quotation" } }
+{ $values { "seq" "a sequence of address specifiers" } { "service" "a string or " { $link f } } { "encoding" "an encoding to use for client connections" } { "quot" "a quotation" } }
 { $description "Starts a TCP/IP server. The quotation is called in a new thread for each client connection, with the client connection being the " { $link stdio } " stream. Client connections are logged to the " { $link stdio } " stream at the time the server was started." } ;
 
 HELP: with-datagrams

extra/logging/analysis/analysis-docs.factor

@@ -16,7 +16,7 @@ HELP: analysis.
 { $description "Prints a logging report output by " { $link analyze-entries } ". Formatted output words are used, so the report looks nice in the UI or if sent to an HTML stream." } ;
 
 HELP: analyze-log
-{ $values { "service" "a log service name" } { "n" integer } { "word-names" "a sequence of strings" } }
+{ $values { "lines" "a parsed log file" } { "word-names" "a sequence of strings" } }
 { $description "Analyzes a log file and prints a formatted report. The " { $snippet "word-names" } " parameter is documented in " { $link analyze-entries } "." } ;
 
 ARTICLE: "logging.analysis" "Log analysis"

extra/logging/insomniac/insomniac-docs.factor

@@ -9,7 +9,7 @@ HELP: insomniac-recipients
 { $var-description "A sequence of e-mail addresses to mail log reports to. Must be set before " { $vocab-link "logging.insomniac" } " is used." } ;
 
 HELP: ?analyze-log
-{ $values { "service" "a log service name" } { "word-names" "a sequence of strings" } { "string" string } }
+{ $values { "service" "a log service name" } { "word-names" "a sequence of strings" } { "string/f" string } }
 { $description "Analyzes the most recent log and outputs the string analysis, or outputs " { $link f } " if it doesn't exist." }
 { $see-also analyze-log } ;
 
@@ -18,7 +18,7 @@ HELP: email-log-report
 { $description "E-mails a log report for the given log service. The " { $link insomniac-sender } " and " { $link insomniac-recipients } " parameters must be set up first. The " { $snippet "word-names" } " parameter is documented in " { $link analyze-entries } "." } ;
 
 HELP: schedule-insomniac
-{ $values { "alist" "a sequence of pairs of shape " { $snippet "{ service word-names }" } } }
+{ $values { "service" "a log service name" } { "word-names" "a sequence of strings" } }
 { $description "Starts a thread which e-mails log reports and rotates logs daily." } ;
 
 ARTICLE: "logging.insomniac" "Automated log analysis"

extra/logging/logging-docs.factor

@@ -39,19 +39,19 @@ HELP: log-message
 { $description "Sends a message to the current log. Does nothing if not executing in a dynamic scope established by " { $link with-logging } "." } ;
 
 HELP: add-logging
-{ $values { "word" word } }
+{ $values { "level" "a log level" } { "word" word } }
 { $description "Causes the word to log a message every time it is called." } ;
 
 HELP: add-input-logging
-{ $values { "word" word } }
+{ $values { "level" "a log level" } { "word" word } }
 { $description "Causes the word to log its input values every time it is called. The word must have a stack effect declaration." } ;
 
 HELP: add-output-logging
-{ $values { "word" word } }
+{ $values { "level" "a log level" } { "word" word } }
 { $description "Causes the word to log its output values every time it is called. The word must have a stack effect declaration." } ;
 
 HELP: add-error-logging
-{ $values { "word" word } }
+{ $values { "level" "a log level" } { "word" word } }
 { $description "Causes the word to log its input values and any errors it throws."
 $nl
 "If the word is not executed in a dynamic scope established by " { $link with-logging } ", its behavior is unchanged, and any errors it throws are passed to the caller."
@@ -63,7 +63,7 @@ HELP: log-error
 { $description "Logs an error." } ;
 
 HELP: log-critical
-{ $values { "critical" "an critical" } { "word" word } }
+{ $values { "error" "an error" } { "word" word } }
 { $description "Logs a critical error." } ;
 
 HELP: LOG:

extra/logging/parser/parser-docs.factor

@@ -6,7 +6,7 @@ HELP: parse-log
 { $description "Parses a sequence of log entries. Malformed entries are printed out and ignore. The result is a sequence of arrays of the shape " { $snippet "{ timestamp level word-name message }" } ", where"
     { $list
         { { $snippet "timestamp" } " is a " { $link timestamp } }
-        { { $snippet "level" } " is a log level; see " { $link "logger.levels" } }
+        { { $snippet "level" } " is a log level; see " { $link "logging.levels" } }
         { { $snippet "word-name" } " is a string" }
         { { $snippet "message" } " is a string" }
     }

extra/math/combinatorics/combinatorics-docs.factor

@@ -4,46 +4,46 @@ IN: math.combinatorics
 HELP: factorial
 { $values { "n" "a non-negative integer" } { "n!" integer } }
 { $description "Outputs the product of all positive integers less than or equal to " { $snippet "n" } "." }
-{ $examples { $example "4 factorial ." "24" } } ;
+{ $examples { $example "USING: math.combinatorics prettyprint ;" "4 factorial ." "24" } } ;
 
 HELP: nPk
 { $values { "n" "a non-negative integer" } { "k" "a non-negative integer" } { "nPk" integer } }
 { $description "Outputs the total number of unique permutations of size " { $snippet "k" } " (order does matter) that can be taken from a set of size " { $snippet "n" } "." }
-{ $examples { $example "10 4 nPk ." "5040" } } ;
+{ $examples { $example "USING: math.combinatorics prettyprint ;" "10 4 nPk ." "5040" } } ;
 
 HELP: nCk
 { $values { "n" "a non-negative integer" } { "k" "a non-negative integer" } { "nCk" integer } }
 { $description "Outputs the total number of unique combinations of size " { $snippet "k" } " (order does not matter) that can be taken from a set of size " { $snippet "n" } ". Commonly written as \"n choose k\"." }
-{ $examples { $example "10 4 nCk ." "210" } } ;
+{ $examples { $example "USING: math.combinatorics prettyprint ;" "10 4 nCk ." "210" } } ;
 
 HELP: permutation
 { $values { "n" "a non-negative integer" } { "seq" sequence } { "seq" sequence } }
 { $description "Outputs the " { $snippet "nth" } " lexicographical permutation of " { $snippet "seq" } "." }
 { $notes "Permutations are 0-based and a bounds error will be thrown if " { $snippet "n" } " is larger than " { $snippet "seq length factorial 1-" } "." }
-{ $examples { $example "1 3 permutation ." "{ 0 2 1 }" } { $example "5 { \"apple\" \"banana\" \"orange\" } permutation ." "{ \"orange\" \"banana\" \"apple\"}" } } ;
+{ $examples { $example "USING: math.combinatorics prettyprint ;" "1 3 permutation ." "{ 0 2 1 }" } { $example "USING: math.combinatorics prettyprint ;" "5 { \"apple\" \"banana\" \"orange\" } permutation ." "{ \"orange\" \"banana\" \"apple\" }" } } ;
 
 HELP: all-permutations
 { $values { "seq" sequence } { "seq" sequence } }
 { $description "Outputs a sequence containing all permutations of " { $snippet "seq" } " in lexicographical order." }
-{ $examples { $example "3 all-permutations ." "{ { 0 1 2 } { 0 2 1 } { 1 0 2 } { 1 2 0 } { 2 0 1 } { 2 1 0 } }" } } ;
+{ $examples { $example "USING: math.combinatorics prettyprint ;" "3 all-permutations ." "{ { 0 1 2 } { 0 2 1 } { 1 0 2 } { 1 2 0 } { 2 0 1 } { 2 1 0 } }" } } ;
 
 HELP: inverse-permutation
 { $values { "seq" sequence } { "permutation" sequence } }
 { $description "Outputs a sequence of indices representing the lexicographical permutation of " { $snippet "seq" } "." }
 { $notes "All items in " { $snippet "seq" } " must be comparable by " { $link <=> } "." }
-{ $examples { $example "\"dcba\" inverse-permutation ." "{ 3 2 1 0 }" } { $example "{ 12 56 34 78 } inverse-permutation ." "{ 0 2 1 3 }" } } ;
+{ $examples { $example "USING: math.combinatorics prettyprint ;" "\"dcba\" inverse-permutation ." "{ 3 2 1 0 }" } { $example "USING: math.combinatorics prettyprint ;" "{ 12 56 34 78 } inverse-permutation ." "{ 0 2 1 3 }" } } ;
 
 
 IN: math.combinatorics.private
 
 HELP: factoradic
-{ $values { "n" integer } { "seq" sequence } }
+{ $values { "n" integer } { "factoradic" sequence } }
 { $description "Converts a positive integer " { $snippet "n" } " to factoradic form.  The factoradic of an integer is its representation based on a mixed radix numerical system that corresponds to the values of " { $snippet "n" } " factorial." }
-{ $examples { $example "859 factoradic ." "{ 1 1 0 3 0 1 0 }" } } ;
+{ $examples { $example "USING: math.combinatorics.private  prettyprint ;" "859 factoradic ." "{ 1 1 0 3 0 1 0 }" } } ;
 
 HELP: >permutation
 { $values { "factoradic" sequence } { "permutation" sequence } }
 { $description "Converts an integer represented in factoradic form into its corresponding unique permutation (0-based)." }
 { $notes "For clarification, the following two statements are equivalent:" { $code "10 factoradic >permutation" "{ 1 2 0 0 } >permutation" } }
-{ $examples { $example "{ 0 0 0 0 } >permutation ." "{ 0 1 2 3 }" } } ;
+{ $examples { $example "USING: math.combinatorics.private prettyprint ;" "{ 0 0 0 0 } >permutation ." "{ 0 1 2 3 }" } } ;
 

extra/math/erato/erato-docs.factor

@@ -3,4 +3,4 @@ IN: math.erato
 
 HELP: lerato
 { $values { "n" "a positive number" } { "lazy-list" "a lazy prime numbers generator" } }
-{ $description "Builds a lazy list containing the prime numbers between 2 and " { $snippet "n" } " (inclusive). Lazy lists are described in " { $link "lazy-lists" } "." } ;
+{ $description "Builds a lazy list containing the prime numbers between 2 and " { $snippet "n" } " (inclusive)." } ;

extra/math/primes/factors/factors-docs.factor

@@ -6,17 +6,17 @@ IN: math.primes.factors
 HELP: factors
 { $values { "n" "a positive integer" } { "seq" sequence } }
 { $description { "Return an ordered list of a number's prime factors, possibly repeated." } }
-{ $examples { $example "300 factors ." "{ 2 2 3 5 5 }" } } ;
+{ $examples { $example "USING: math.primes.factors prettyprint ;" "300 factors ." "{ 2 2 3 5 5 }" } } ;
 
 HELP: group-factors
 { $values { "n" "a positive integer" } { "seq" sequence } }
 { $description { "Return a sequence of pairs representing each prime factor in the number and its corresponding power (multiplicity)." } }
-{ $examples { $example "300 group-factors ." "{ { 2 2 } { 3 1 } { 5 2 } }" } } ;
+{ $examples { $example "USING: math.primes.factors prettyprint ;" "300 group-factors ." "{ { 2 2 } { 3 1 } { 5 2 } }" } } ;
 
 HELP: unique-factors
 { $values { "n" "a positive integer" } { "seq" sequence } }
 { $description { "Return an ordered list of a number's unique prime factors." } }
-{ $examples { $example "300 unique-factors ." "{ 2 3 5 }" } } ;
+{ $examples { $example "USING: math.primes.factors prettyprint ;" "300 unique-factors ." "{ 2 3 5 }" } } ;
 
 HELP: totient
 { $values { "n" "a positive integer" } { "t" integer } }

extra/math/statistics/statistics-docs.factor

@@ -4,56 +4,56 @@ IN: math.statistics
 HELP: geometric-mean
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
 { $description "Computes the geometric mean of all elements in " { $snippet "seq" } ".  The geometric mean measures the central tendency of a data set that minimizes the effects of extreme values." }
-{ $examples { $example "USE: math.statistics" "{ 1 2 3 } geometric-mean ." "1.81712059283214" } }
+{ $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } geometric-mean ." "1.81712059283214" } }
 { $errors "Throws a " { $link signal-error. } " (square-root of 0) if the sequence is empty." } ;
 
 HELP: harmonic-mean
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
 { $description "Computes the harmonic mean of the elements in " { $snippet "seq" } ".  The harmonic mean is appropriate when the average of rates is desired." }
-{ $examples { $example "USE: math.statistics" "{ 1 2 3 } harmonic-mean ." "6/11" } }
+{ $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } harmonic-mean ." "6/11" } }
 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
 
 HELP: mean
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
 { $description "Computes the arithmetic mean of all elements in " { $snippet "seq" } "." }
-{ $examples { $example "USE: math.statistics" "{ 1 2 3 } mean ." "2" } }
+{ $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } mean ." "2" } }
 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
 
 HELP: median
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
 { $description "Computes the median of " { $snippet "seq" } " by sorting the sequence from lowest value to highest and outputting the middle one. If there is an even number of elements in the sequence, the median is not unique, so the mean of the two middle values is outputted." }
 { $examples
-  { $example "USE: math.statistics" "{ 1 2 3 } median ." "2" }
-  { $example "USE: math.statistics" "{ 1 2 3 4 } median ." "5/2" } }
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } median ." "2" }
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } median ." "2+1/2" } }
 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
 
 HELP: range
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
 { $description "Computes the distance of the maximum and minimum values in " { $snippet "seq" } "." }
 { $examples
-  { $example "USE: math.statistics" "{ 1 2 3 } range ." "2" }
-  { $example "USE: math.statistics" "{ 1 2 3 4 } range ." "3" } }  ;
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } range ." "2" }
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } range ." "3" } }  ;
 
 HELP: std
 { $values { "seq" "a sequence of numbers" } { "x" "a non-negative real number"} }
 { $description "Computes the standard deviation of " { $snippet "seq" } " by squaring the variance of the sequence.  It measures how widely spread the values in a sequence are about the mean." }
 { $examples
-  { $example "USE: math.statistics" "{ 1 2 3 } std ." "1.0" }
-  { $example "USE: math.statistics" "{ 1 2 3 4 } std ." "1.290994448735806" } } ;
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } std ." "1.0" }
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } std ." "1.290994448735806" } } ;
 
 HELP: ste
   { $values { "seq" "a sequence of numbers" } { "x" "a non-negative real number"} }
   { $description "Computes the standard error of the mean for " { $snippet "seq" } ".  It's defined as the standard deviation divided by the square root of the length of the sequence, and measures uncertainty associated with the estimate of the mean." }
   { $examples
-    { $example "USE: math.statistics" "{ -2 2 } ste ." "2.0" }
-    { $example "USE: math.statistics" "{ -2 2 2 } ste ." "1.333333333333333" } } ;
+    { $example "USING: math.statistics prettyprint ;" "{ -2 2 } ste ." "2.0" }
+    { $example "USING: math.statistics prettyprint ;" "{ -2 2 2 } ste ." "1.333333333333333" } } ;
 
 HELP: var
 { $values { "seq" "a sequence of numbers" } { "x" "a non-negative real number"} }
 { $description "Computes the variance of " { $snippet "seq" } ".  It's a measurement of the spread of values in a sequence.  The larger the variance, the larger the distance of values from the mean." }
 { $notes "If the number of elements in " { $snippet "seq" } " is 1 or less, it outputs 0." }
 { $examples
-  { $example "USE: math.statistics" "{ 1 } var ." "0" }
-  { $example "USE: math.statistics" "{ 1 2 3 } var ." "1" }
-  { $example "USE: math.statistics" "{ 1 2 3 4 } var ." "5/3" } } ;
+  { $example "USING: math.statistics prettyprint ;" "{ 1 } var ." "0" }
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } var ." "1" }
+  { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } var ." "1+2/3" } } ;
 

extra/math/text/english/english-docs.factor

@@ -4,4 +4,4 @@ IN: math.text.english
 HELP: number>text
 { $values { "n" integer } { "str" string } }
 { $description "Converts an integer to a text string representation in English, including appropriate punctuation and conjunctions." }
-{ $examples { $example "12345 number>text ." "\"Twelve Thousand, Three Hundred and Forty-Five\"" } } ;
+{ $examples { $example "USING: math.text.english prettyprint ;" "12345 number>text ." "\"Twelve Thousand, Three Hundred and Forty-Five\"" } } ;

extra/opengl/capabilities/capabilities-docs.factor

@@ -43,7 +43,7 @@ HELP: has-gl-extensions?
 { $description "Returns true if the set of " { $snippet "extensions" } " is a subset of the implementation-supported extensions returned by " { $link gl-extensions } "." } ;
 
 HELP: has-gl-version-or-extensions?
-{ $values { "version" "A version string" } { "extensions" "A sequence of extension name strings" } }
+{ $values { "version" "A version string" } { "extensions" "A sequence of extension name strings" } { "?" "a boolean" } }
 { $description "Returns true if either " { $link has-gl-version? } " or " { $link has-gl-extensions? } " returns true for " { $snippet "version" } " or " { $snippet "extensions" } ", respectively. Intended for use when required OpenGL functionality can be verified either by a minimum version or a set of equivalent extensions." } ;
 
 HELP: require-gl-extensions

extra/opengl/shaders/shaders-docs.factor

@@ -1,5 +1,5 @@
 USING: help.markup help.syntax io kernel math quotations
-opengl.gl multiline assocs ;
+opengl.gl multiline assocs strings ;
 IN: opengl.shaders
 
 HELP: gl-shader
@@ -28,19 +28,19 @@ HELP: fragment-shader
 } ;
 
 HELP: <gl-shader>
-{ $values { "source" "The GLSL source code to compile" } { "kind" "The kind of shader to compile, such as " { $snippet "GL_VERTEX_SHADER" } " or " { $snippet "GL_FRAGMENT_SHADER" } } }
+{ $values { "source" "The GLSL source code to compile" } { "kind" "The kind of shader to compile, such as " { $snippet "GL_VERTEX_SHADER" } " or " { $snippet "GL_FRAGMENT_SHADER" } } { "shader" "a new " { $link gl-shader } } }
 { $description "Tries to compile the given GLSL source into a shader object. The returned object can be checked for validity by " { $link check-gl-shader } " or " { $link gl-shader-ok? } ". Errors and warnings generated by the GLSL compiler will be collected in the info log, available from " { $link gl-shader-info-log } ".\n\nWhen the shader object is no longer needed, it should be deleted using " { $link delete-gl-shader } " or else be attached to a " { $link gl-program } " object deleted using " { $link delete-gl-program } "." } ;
 
 HELP: <vertex-shader>
-{ $values { "source" "The GLSL source code to compile" } }
+{ $values { "source" "The GLSL source code to compile" } { "vertex-shader" "a new " { $link vertex-shader } } }
 { $description "Tries to compile the given GLSL source into a vertex shader object. Equivalent to " { $snippet "GL_VERTEX_SHADER <gl-shader>" } "." } ;
 
 HELP: <fragment-shader>
-{ $values { "source" "The GLSL source code to compile" } }
+{ $values { "source" "The GLSL source code to compile" } { "fragment-shader" "a new " { $link fragment-shader } } }
 { $description "Tries to compile the given GLSL source into a fragment shader object. Equivalent to " { $snippet "GL_FRAGMENT_SHADER <gl-shader>" } "." } ;
 
 HELP: gl-shader-ok?
-{ $values { "shader" "A " { $link gl-shader } " object" } }
+{ $values { "shader" "A " { $link gl-shader } " object" } { "?" "a boolean" } }
 { $description "Returns a boolean value indicating whether the given shader object compiled successfully. Compilation errors and warnings are available in the shader's info log, which can be gotten using " { $link gl-shader-info-log } "." } ;
 
 HELP: check-gl-shader
@@ -52,7 +52,7 @@ HELP: delete-gl-shader
 { $description "Deletes the shader object, invalidating it and releasing any resources allocated for it by the OpenGL implementation." } ;
 
 HELP: gl-shader-info-log
-{ $values { "shader" "A " { $link gl-shader } " object" } }
+{ $values { "shader" "A " { $link gl-shader } " object" } { "shader" "a new " { $link gl-shader } } { "log" string } }
 { $description "Retrieves the info log for " { $snippet "shader" } ", including any errors or warnings generated in compiling the shader object." } ;
 
 HELP: gl-program
@@ -69,17 +69,17 @@ HELP: gl-program
 } ;
 
 HELP: <gl-program>
-{ $values { "shaders" "A sequence of " { $link gl-shader } " objects." } }
+{ $values { "shaders" "A sequence of " { $link gl-shader } " objects." } { "program" "a new " { $link gl-program } } } 
 { $description "Creates a new GLSL program object, attaches all the shader objects in the " { $snippet "shaders" } " sequence, and attempts to link them. The returned object can be checked for validity by " { $link check-gl-program } " or " { $link gl-program-ok? } ". Errors and warnings generated by the GLSL linker will be collected in the info log, available from " { $link gl-program-info-log } ".\n\nWhen the program object and its attached shaders are no longer needed, it should be deleted using " { $link delete-gl-program } "." } ;
 
 HELP: <simple-gl-program>
-{ $values { "vertex-shader-source" "A string containing GLSL vertex shader source" } { "fragment-shader-source" "A string containing GLSL fragment shader source" } }
+{ $values { "vertex-shader-source" "A string containing GLSL vertex shader source" } { "fragment-shader-source" "A string containing GLSL fragment shader source" } { "program" "a new " { $link gl-program } } }
 { $description "Wrapper for " { $link <gl-program> } " for the simple case of compiling a single vertex shader and fragment shader and linking them into a GLSL program. Throws an exception if compiling or linking fails." } ;
 
 { <gl-program> <simple-gl-program> } related-words
 
 HELP: gl-program-ok?
-{ $values { "program" "A " { $link gl-program } " object" } }
+{ $values { "program" "A " { $link gl-program } " object" } { "?" "a boolean" } }
 { $description "Returns a boolean value indicating whether the given program object linked successfully. Link errors and warnings are available in the program's info log, which can be gotten using " { $link gl-program-info-log } "." } ;
 
 HELP: check-gl-program
@@ -87,7 +87,7 @@ HELP: check-gl-program
 { $description "Throws an error containing the " { $link gl-program-info-log } " for the program object if it failed to link. Otherwise, the program object is left on the stack." } ;
 
 HELP: gl-program-info-log
-{ $values { "program" "A " { $link gl-program } " object" } }
+{ $values { "program" "A " { $link gl-program } " object" } { "log" string } }
 { $description "Retrieves the info log for " { $snippet "program" } ", including any errors or warnings generated in linking the program object." } ;
 
 HELP: delete-gl-program

extra/opengl/shaders/shaders.factor

@@ -50,7 +50,7 @@ IN: opengl.shaders
         alien>char-string
     ] with-malloc ;
 
-: check-gl-shader ( shader -- shader* )
+: check-gl-shader ( shader -- shader )
     dup gl-shader-ok? [ dup gl-shader-info-log throw ] unless ;
 
 : delete-gl-shader ( shader -- ) glDeleteShader ; inline
@@ -85,7 +85,7 @@ PREDICATE: gl-shader fragment-shader (fragment-shader?) ;
         alien>char-string
     ] with-malloc ;
 
-: check-gl-program ( program -- program* )
+: check-gl-program ( program -- program )
     dup gl-program-ok? [ dup gl-program-info-log throw ] unless ;
 
 : gl-program-shaders-length ( program -- shaders-length )

extra/peg/search/search-docs.factor

@@ -10,7 +10,7 @@ HELP: tree-write
     "Write the object to the standard output stream, unless "
     "it is an array, in which case recurse through the array "
     "writing each object to the stream." }
-{ $example "{ 65 \"bc\" { 68 \"ef\" } } tree-write" "AbcDef" } ;
+{ $example "USE: peg.search" "{ 65 \"bc\" { 68 \"ef\" } } tree-write" "AbcDef" } ;
 
 HELP: search
 { $values
@@ -24,8 +24,8 @@ HELP: search
     "parser."
 }
 
-{ $example "\"one 123 two 456\" 'integer' search" "V{ 123 456 }" }
-{ $example "\"one 123 \\\"hello\\\" two 456\" 'integer' 'string' 2array choice search" "V{ 123 \"hello\" 456 }" }
+{ $example "USING: peg.parsers peg.search prettyprint ;" "\"one 123 two 456\" 'integer' search ." "V{ 123 456 }" }
+{ $example "USING: peg peg.parsers peg.search prettyprint ;" "\"one 123 \\\"hello\\\" two 456\" 'integer' 'string' 2choice search ." "V{ 123 \"hello\" 456 }" }
 { $see-also replace } ;
 
 HELP: replace
@@ -39,6 +39,6 @@ HELP: replace
     "successfully parse with the given parser replaced with "
     "the result of that parser."
 }
-{ $example "\"one 123 two 456\" 'integer' [ 2 * number>string ] action replace" "\"one 246 two 912\"" }
+{ $example "USING: math math.parser peg peg.parsers peg.search prettyprint ;" "\"one 123 two 456\" 'integer' [ 2 * number>string ] action replace ." "\"one 246 two 912\"" }
 { $see-also search } ;
 

extra/serialize/serialize-docs.factor

@@ -8,7 +8,7 @@ HELP: serialize
 }
 { $description "Serializes the object to the current output stream. Object references within the structure being serialized are maintained." } 
 { $examples 
-    { $example "USING: serialize io.streams.string ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" }
+    { $example "USING: serialize io.encodings.binary io.streams.byte-array prettyprint ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" }
 }
 { $see-also deserialize } ;
 
@@ -17,6 +17,6 @@ HELP: deserialize
 }
 { $description "Deserializes an object by reading from the current input stream. Object references within the structure that was originally serialized are maintained." } 
 { $examples 
-    { $example "USING: serialize io.streams.string ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" }
+    { $example "USING: serialize io.encodings.binary io.streams.byte-array prettyprint ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" }
 }
 { $see-also serialize } ;

extra/singleton/singleton-docs.factor

@@ -8,7 +8,7 @@ HELP: SINGLETON:
 } { $description
     "Defines a new predicate class whose superclass is " { $link word } ".  Only one instance of a singleton may exist because classes are " { $link eq? } " to themselves.  Methods may be defined on a singleton."
 } { $examples
-    { $example "SINGLETON: foo\nGENERIC: bar ( obj -- )\nM: foo bar drop \"a foo!\" print ;\nfoo bar" "a foo!" }
+    { $example "USING: singleton kernel io ;" "SINGLETON: foo\nGENERIC: bar ( obj -- )\nM: foo bar drop \"a foo!\" print ;\nfoo bar" "a foo!" }
 } { $see-also
     POSTPONE: PREDICATE:
 } ;
@@ -20,7 +20,7 @@ HELP: SINGLETONS:
 } { $description
     "Defines a new singleton for each class in the list."
 } { $examples
-    { $example "SINGLETONS: foo bar baz ;" "" }
+    { $example "USE: singleton" "SINGLETONS: foo bar baz ;" "" }
 } { $see-also
     POSTPONE: SINGLETON:
 } ;

extra/trees/splay/splay-docs.factor

@@ -11,7 +11,7 @@ HELP: <splay>
 { $description "Creates an empty splay tree" } ;
 
 HELP: >splay
-{ $values { "assoc" assoc } { "splay" splay } }
+{ $values { "assoc" assoc } { "tree" splay } }
 { $description "Converts any " { $link assoc } " into an splay tree." } ;
 
 HELP: splay

extra/trees/splay/splay.factor

@@ -6,7 +6,7 @@ IN: trees.splay
 
 TUPLE: splay ;
 
-: <splay> ( -- splay-tree )
+: <splay> ( -- tree )
     \ splay construct-tree ;
 
 INSTANCE: splay tree-mixin
@@ -130,7 +130,7 @@ M: splay delete-at ( key tree -- )
 M: splay new-assoc
     2drop <splay> ;
 
-: >splay ( assoc -- splay-tree )
+: >splay ( assoc -- tree )
     T{ splay T{ tree f f 0 } } assoc-clone-like ;
 
 : SPLAY{

extra/tuples/lib/lib-docs.factor

@@ -5,7 +5,7 @@ HELP: >tuple<
 { $values { "class" "a tuple class" } }
 { $description "Explodes the tuple so that tuple slots are on the stack in the order listed in the tuple." }
 { $example
-    "USE: tuples.lib"
+    "USING: kernel prettyprint tuples.lib ;"
     "TUPLE: foo a b c ;"
     "1 2 3 \\ foo construct-boa \\ foo >tuple< .s"
     "1\n2\n3"
@@ -17,7 +17,7 @@ HELP: >tuple*<
 { $values { "class" "a tuple class" } }
 { $description "Explodes the tuple so that tuple slots ending with '*' are on the stack in the order listed in the tuple." }
 { $example
-    "USE: tuples.lib"
+    "USING: kernel prettyprint tuples.lib ;"
     "TUPLE: foo a bb* ccc dddd* ;"
     "1 2 3 4 \\ foo construct-boa \\ foo >tuple*< .s"
     "2\n4"

extra/xml/xml-docs.factor

@@ -170,7 +170,7 @@ HELP: <instruction> ( text -- instruction )
 HELP: names-match?
 { $values { "name1" "a name" } { "name2" "a name" } { "?" "t or f" } }
 { $description "checks to see if the two names match, that is, if all fields are equal, ignoring fields whose value is f in either name." }
-{ $example "USE: xml.data" "T{ name f \"rpc\" \"methodCall\" f } T{ name f f \"methodCall\" \"http://www.xmlrpc.org/\" } names-match? ." "t" }
+{ $example "USING: prettyprint xml.data ;" "T{ name f \"rpc\" \"methodCall\" f } T{ name f f \"methodCall\" \"http://www.xmlrpc.org/\" } names-match? ." "t" }
 { $see-also name } ;
 
 HELP: xml-chunk