From 4e9d383fe5dedb0994e40f2e62e0fb3eb3944ba8 Mon Sep 17 00:00:00 2001
From: Doug Coleman <doug.coleman@gmail.com>
Date: Sat, 7 Jul 2018 00:44:46 -0500
Subject: [PATCH] docs: Fix help-lint-all mistakes.

---
 basis/alien/libraries/libraries-docs.factor   |  6 ++---
 .../image/primitives/primitives-docs.factor   |  2 +-
 .../compiler/cfg/builder/builder-docs.factor  | 12 +++++-----
 .../assignment/assignment-docs.factor         |  2 +-
 .../linear-scan/assignment/assignment.factor  |  2 +-
 .../cfg/stacks/local/local-docs.factor        |  9 ++++----
 .../cpu/architecture/architecture-docs.factor |  9 +++++++-
 basis/cpu/architecture/architecture.factor    |  2 +-
 basis/english/english-docs.factor             |  4 ++--
 basis/help/topics/topics.factor               |  2 +-
 basis/io/directories/directories-docs.factor  |  2 +-
 basis/lists/lazy/lazy-docs.factor             |  4 ++--
 basis/math/vectors/vectors-docs.factor        |  2 +-
 basis/opengl/shaders/shaders-docs.factor      |  1 +
 .../dependencies/dependencies-docs.factor     |  2 +-
 basis/suffix-arrays/suffix-arrays-docs.factor |  2 +-
 basis/typed/typed-docs.factor                 |  4 ++--
 basis/ui/backend/gtk/gtk-docs.factor          |  6 ++---
 basis/vocabs/metadata/metadata-docs.factor    |  2 +-
 basis/wrap/words/words-docs.factor            |  2 +-
 basis/wrap/wrap-docs.factor                   |  4 ++--
 core/alien/alien-docs.factor                  |  2 +-
 core/classes/tuple/tuple-docs.factor          |  2 +-
 core/kernel/kernel-docs.factor                | 10 ++++----
 core/math/math-docs.factor                    |  2 +-
 core/sequences/sequences-docs.factor          |  8 +++----
 extra/ctags/ctags-docs.factor                 |  2 +-
 extra/fuel/help/help-docs.factor              |  2 +-
 extra/gpu/shaders/shaders-docs.factor         |  1 +
 extra/odbc/odbc-docs.factor                   |  4 ++--
 extra/successor/successor-docs.factor         |  2 +-
 extra/trees/trees-docs.factor                 |  4 ++--
 .../ui/gadgets/charts/lines/lines-docs.factor | 23 +++++++++++++++++++
 33 files changed, 88 insertions(+), 55 deletions(-)

diff --git a/basis/alien/libraries/libraries-docs.factor b/basis/alien/libraries/libraries-docs.factor
index 366cc91da6..582b607f32 100644
--- a/basis/alien/libraries/libraries-docs.factor
+++ b/basis/alien/libraries/libraries-docs.factor
@@ -1,7 +1,7 @@
 ! Copyright (C) 2009 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: alien alien.syntax assocs help.markup help.syntax strings words
-;
+USING: alien alien.syntax assocs help.markup help.syntax kernel
+strings ;
 IN: alien.libraries
 
 HELP: add-library
@@ -73,7 +73,7 @@ HELP: library
 } ;
 
 HELP: library-dll
-{ $values { "name" string } { "dll" "a DLL handle" } }
+{ $values { "obj" object } { "dll" "a DLL handle" } }
 { $description "Looks up a library by logical name and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." } ;
 
 HELP: remove-library
diff --git a/basis/bootstrap/image/primitives/primitives-docs.factor b/basis/bootstrap/image/primitives/primitives-docs.factor
index 78b9f08056..ce435ac5a7 100644
--- a/basis/bootstrap/image/primitives/primitives-docs.factor
+++ b/basis/bootstrap/image/primitives/primitives-docs.factor
@@ -19,7 +19,7 @@ HELP: primitive-quot
 { $description "Creates the defining quotation for the primitive. If 'vm-func' is a string, then it is prefixed with 'primitive_' and a quotation calling that C++ function is generated." } ;
 
 ARTICLE: "bootstrap.image.primitives" "Bootstrap primitives"
-"This vocab contains utilities for declaring primitives to be added to the bootstrap image. It is used by " { $vocab-link "bootstrap.primitives" }
+"This vocab contains utilities for declaring primitives to be added to the bootstrap image. It is used by the file " { $snippet "resource:core/bootstrap/primitives.factor" }
 $nl
 { $link all-primitives } " is an assoc where all primitives are declared. See that constant for a description of the format." ;
 
diff --git a/basis/compiler/cfg/builder/builder-docs.factor b/basis/compiler/cfg/builder/builder-docs.factor
index f57320b4b5..308c3e4ff0 100644
--- a/basis/compiler/cfg/builder/builder-docs.factor
+++ b/basis/compiler/cfg/builder/builder-docs.factor
@@ -1,7 +1,7 @@
-USING: assocs compiler.cfg compiler.cfg.builder.blocks
-compiler.cfg.instructions compiler.cfg.stacks.local compiler.tree
-help.markup help.syntax kernel literals math multiline quotations
-sequences vectors words ;
+USING: arrays assocs compiler.cfg compiler.cfg.builder.blocks
+compiler.cfg.instructions compiler.cfg.stacks.local
+compiler.tree help.markup help.syntax kernel literals math
+multiline quotations sequences vectors words ;
 IN: compiler.cfg.builder
 
 <<
@@ -104,7 +104,7 @@ HELP: end-word
 { $description "Ends the word by adding a basic block containing a " { $link ##return } " instructions to the " { $link cfg } "." } ;
 
 HELP: height-changes
-{ $values { "#shuffle" #shuffle } { "height-changes" sequence } }
+{ $values { "#shuffle" #shuffle } { "height-changes" pair } }
 { $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." }
 { $examples
   { $example
@@ -115,7 +115,7 @@ HELP: height-changes
 } ;
 
 HELP: out-vregs/stack
-{ $values { "#shuffle" #shuffle } { "seq" sequence } }
+{ $values { "#shuffle" #shuffle } { "pair" sequence } }
 { $description "Returns a sequence of what vregs are on which stack locations after the shuffle instruction." } ;
 
 HELP: trivial-branch?
diff --git a/basis/compiler/cfg/linear-scan/assignment/assignment-docs.factor b/basis/compiler/cfg/linear-scan/assignment/assignment-docs.factor
index 6d9ad819bd..646c0d8674 100644
--- a/basis/compiler/cfg/linear-scan/assignment/assignment-docs.factor
+++ b/basis/compiler/cfg/linear-scan/assignment/assignment-docs.factor
@@ -72,7 +72,7 @@ HELP: vreg>reg
 { $see-also lookup-spill-slot pending-interval-assoc } ;
 
 HELP: vregs>regs
-{ $values { "assoc" "an " { $link assoc } " (set) of virtual registers" } { "assoc" assoc } }
+{ $values { "assoc" "an " { $link assoc } " (set) of virtual registers" } { "assoc'" assoc } }
 { $description "Creates a mapping of virtual registers to registers." } ;
 
 HELP: vreg>spill-slot
diff --git a/basis/compiler/cfg/linear-scan/assignment/assignment.factor b/basis/compiler/cfg/linear-scan/assignment/assignment.factor
index b5ffb4d0ee..37fb24b2d4 100644
--- a/basis/compiler/cfg/linear-scan/assignment/assignment.factor
+++ b/basis/compiler/cfg/linear-scan/assignment/assignment.factor
@@ -29,7 +29,7 @@ SYMBOL: pending-interval-assoc
 : remove-pending ( live-interval -- )
     vreg>> pending-interval-assoc get delete-at ;
 
-: vreg>spill-slot ( vreg -- slot )
+: vreg>spill-slot ( vreg -- spill-slot )
     dup rep-of lookup-spill-slot ;
 
 : vreg>reg ( vreg -- reg/spill-slot )
diff --git a/basis/compiler/cfg/stacks/local/local-docs.factor b/basis/compiler/cfg/stacks/local/local-docs.factor
index a3e7d8919b..0131a1098d 100644
--- a/basis/compiler/cfg/stacks/local/local-docs.factor
+++ b/basis/compiler/cfg/stacks/local/local-docs.factor
@@ -51,7 +51,7 @@ HELP: height-state
 { $see-also inc-stack reset-incs } ;
 
 HELP: height-state>insns
-{ $values { "state" sequence } { "insns" sequence } }
+{ $values { "height-state" height-state } { "insns" sequence } }
 { $description "Converts a " { $link height-state } " tuple to 0-2 stack height change instructions." }
 { $examples
   "In this example the datastacks height is increased by 4 and the retainstacks decreased by 2."
@@ -67,7 +67,7 @@ HELP: inc-stack
 { $description "Increases or decreases the data or retain stack depending on if loc is a " { $link ds-loc } " or " { $link rs-loc } " instance. An " { $link ##inc } " instruction will later be inserted." } ;
 
 HELP: local-loc>global
-{ $values { "loc" loc } { "bb" basic-block } { "loc'" loc } }
+{ $values { "loc" loc } { "height-state" height-state } { "loc'" loc } }
 { $description "Translates a stack location relative to a block to an absolute one. The word does the opposite to " { $link global-loc>local } "." } ;
 
 HELP: loc>vreg
@@ -76,10 +76,11 @@ HELP: loc>vreg
 
 HELP: local-kill-set
 { $values
-  { "ds-height" integer }
+  { "ds-begin" integer }
   { "ds-inc" integer }
-  { "rs-height" integer }
+  { "rs-begin" integer }
   { "rs-inc" integer }
+  { "set" hash-set }
 }
 { $description "The set of stack locations that was killed. Locations on a stack are deemed killed if that stacks height is decremented." }
 { $see-also compute-local-kill-set } ;
diff --git a/basis/cpu/architecture/architecture-docs.factor b/basis/cpu/architecture/architecture-docs.factor
index 4adaae350a..8d1788b57f 100644
--- a/basis/cpu/architecture/architecture-docs.factor
+++ b/basis/cpu/architecture/architecture-docs.factor
@@ -75,6 +75,7 @@ init-relocation [ RAX RBX 3 -14 RCX RDX %write-barrier ] B{ } make disassemble
 
 HELP: %alien-invoke
 { $values
+  { "varargs?" boolean }
   { "reg-inputs" sequence }
   { "stack-inputs" sequence }
   { "reg-outputs" sequence }
@@ -292,12 +293,18 @@ HELP: %store-memory-imm
 HELP: %test-imm-branch
 { $values
   { "label" "branch destination" }
+  { "cc" "comparison symbol" }
   { "src1" "register" }
   { "src2" "immediate" }
-  { "cc" "comparison symbol" }
 } { $description "Emits a TEST instruction with a register and an immediate, followed by a branch." } ;
 
 HELP: %unbox
+{ $values
+  { "dst" "destination register" }
+  { "src" "source register" }
+  { "func" "function?" }
+  { "rep" representation }
+}
 { $description "Call a function to convert a tagged pointer into a value that can be passed to a C function, or returned from a callback." } ;
 
 HELP: %vector>scalar
diff --git a/basis/cpu/architecture/architecture.factor b/basis/cpu/architecture/architecture.factor
index 55b13c48b5..83de9fbf6b 100644
--- a/basis/cpu/architecture/architecture.factor
+++ b/basis/cpu/architecture/architecture.factor
@@ -522,7 +522,7 @@ HOOK: fused-unboxing? cpu ( -- ? )
 HOOK: immediate-arithmetic? cpu ( n -- ? )
 HOOK: immediate-bitwise? cpu ( n -- ? )
 HOOK: immediate-comparand? cpu ( n -- ? )
-HOOK: immediate-store? cpu ( obj -- ? )
+HOOK: immediate-store? cpu ( n -- ? )
 
 M: object immediate-comparand? ( n -- ? )
     {
diff --git a/basis/english/english-docs.factor b/basis/english/english-docs.factor
index 4cbe1a5e96..e025a04aa9 100644
--- a/basis/english/english-docs.factor
+++ b/basis/english/english-docs.factor
@@ -110,7 +110,7 @@ HELP: count-of-things
 } ;
 
 HELP: ?pluralize
-{ $values { "count" number } { "singular" string } { "singluar/plural" string } }
+{ $values { "count" number } { "singular" string } { "singular/plural" string } }
 { $description "A simpler variant of " { $link count-of-things } " which omits its input value from the output. As with " { $link count-of-things } ", " { $snippet "word" } " is expected to be in singular form." }
 { $notes { $list $keep-case $0-plurality } }
 { $examples
@@ -189,7 +189,7 @@ HELP: comma-list
 } ;
 
 HELP: or-markup-example
-{ $values { "markup" "a sequence of markup elements" } { "classes" "a sequence of words" } }
+{ $values { "classes" "a sequence of words" } { "markup" "a sequence of markup elements" } }
 { $description "Used to implement " { $link $or-markup-example } " and demonstrate " { $link comma-list } "." }
 { $examples { "See the examples in " { $link $or-markup-example } "." } } ;
 
diff --git a/basis/help/topics/topics.factor b/basis/help/topics/topics.factor
index e52486d3ee..635b459d0d 100644
--- a/basis/help/topics/topics.factor
+++ b/basis/help/topics/topics.factor
@@ -42,7 +42,7 @@ GENERIC: valid-article? ( topic -- ? )
 GENERIC: article-title ( topic -- string )
 GENERIC: article-name ( topic -- string )
 GENERIC: article-content ( topic -- content )
-GENERIC: article-parent ( topic -- parent )
+GENERIC: article-parent ( topic -- parent/f )
 GENERIC: set-article-parent ( parent topic -- )
 
 M: object article-name article-title ;
diff --git a/basis/io/directories/directories-docs.factor b/basis/io/directories/directories-docs.factor
index caf2913cf2..db49a4bdd0 100644
--- a/basis/io/directories/directories-docs.factor
+++ b/basis/io/directories/directories-docs.factor
@@ -20,7 +20,7 @@ $nl
   "This variable should never be set directly; instead, use " { $link set-current-directory } " or " { $link with-directory } ". This preserves the invariant that the value of this variable is an absolute path." } ;
 
 HELP: make-parent-directories
-{ $values { "path" "a pathname string" } }
+{ $values { "filename" "a pathname string" } }
 { $description "Creates all parent directories of the path which do not yet exist." }
 { $errors "Throws an error if the directories could not be created." } ;
 
diff --git a/basis/lists/lazy/lazy-docs.factor b/basis/lists/lazy/lazy-docs.factor
index ac9e053985..fa43da2186 100644
--- a/basis/lists/lazy/lazy-docs.factor
+++ b/basis/lists/lazy/lazy-docs.factor
@@ -109,11 +109,11 @@ HELP: lappend-lazy
 { $description "Perform a similar functionality to that of the " { $link append } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link lazy-append } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required. Successive calls to " { $link cdr } " will iterate through list1, followed by list2." } ;
 
 HELP: lfrom-by
-{ $values { "n" integer } { "quot" { $quotation ( n -- o ) } } { "lazy-from-by" "a lazy list of integers" } }
+{ $values { "n" integer } { "quot" { $quotation ( n -- o ) } } { "result" "a lazy list of integers" } }
 { $description "Return an infinite lazy list of values starting from n, with each successive value being the result of applying quot to the previous value." } ;
 
 HELP: lfrom
-{ $values { "n" integer } { "list" "a lazy list of integers" } }
+{ $values { "n" integer } { "result" "a lazy list of integers" } }
 { $description "Return an infinite lazy list of incrementing integers starting from n." } ;
 
 HELP: sequence-tail>list
diff --git a/basis/math/vectors/vectors-docs.factor b/basis/math/vectors/vectors-docs.factor
index 5c928f8e5b..24f5866d42 100644
--- a/basis/math/vectors/vectors-docs.factor
+++ b/basis/math/vectors/vectors-docs.factor
@@ -304,7 +304,7 @@ HELP: vmin
 { $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
 
 HELP: vclamp
-{ $values { "v" "a sequence of real numbers" } { "min" "a sequence of real numbers" } { "max" "a sequence of real numbers" } }
+{ $values { "v" "a sequence of real numbers" } { "min" "a sequence of real numbers" } { "max" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
 { $description "Creates a sequence where each element is clamped to the minimum and maximum elements of the " { $snippet "min" } " and " { $snippet "max" } " sequences." }
 { $examples
   { $example
diff --git a/basis/opengl/shaders/shaders-docs.factor b/basis/opengl/shaders/shaders-docs.factor
index 7051364386..7b314f92ed 100644
--- a/basis/opengl/shaders/shaders-docs.factor
+++ b/basis/opengl/shaders/shaders-docs.factor
@@ -6,6 +6,7 @@ HELP: (gl-program)
 { $values
   { "shaders" sequence }
   { "quot" quotation }
+  { "program" "a new " { $link gl-program } }
 } { $description
     "Creates a gl program and attaches the shaders to it. Then applies the quotation to the program and finally links it."
   }
diff --git a/basis/stack-checker/dependencies/dependencies-docs.factor b/basis/stack-checker/dependencies/dependencies-docs.factor
index d80880ad70..2f5167eb8a 100644
--- a/basis/stack-checker/dependencies/dependencies-docs.factor
+++ b/basis/stack-checker/dependencies/dependencies-docs.factor
@@ -11,7 +11,7 @@ HELP: +definition+
 { $description "Word that indicates that the dependency is a definition dependency. It is a dependency among two words in which one word depends on the definition of the another. For example, if two words are defined as " { $snippet ": o ( -- ) i ;" } " and " { $snippet ": i ( -- ) ; inline" } ", then 'o' has a definition dependency to 'i' because 'i' is inline. If the definition of 'i' changes 'o' must be recompiled." } ;
 
 HELP: add-depends-on-class
-{ $values { "obj" classoid } }
+{ $values { "classoid" classoid } }
 { $description "Adds a " { $link +conditional+ } " dependency from the word to the classes mentioned in the classoid." } ;
 
 HELP: conditional-dependencies
diff --git a/basis/suffix-arrays/suffix-arrays-docs.factor b/basis/suffix-arrays/suffix-arrays-docs.factor
index de8b0f2366..455756bd7d 100644
--- a/basis/suffix-arrays/suffix-arrays-docs.factor
+++ b/basis/suffix-arrays/suffix-arrays-docs.factor
@@ -7,7 +7,7 @@ IN: suffix-arrays
 HELP: >suffix-array
 { $values
      { "seq" sequence }
-     { "array" array } }
+     { "suffix-array" array } }
 { $description "Creates a suffix array from the input sequence. Suffix arrays are arrays of slices." } ;
 
 HELP: SA{
diff --git a/basis/typed/typed-docs.factor b/basis/typed/typed-docs.factor
index 8f2e0e6f36..262a0a03e0 100644
--- a/basis/typed/typed-docs.factor
+++ b/basis/typed/typed-docs.factor
@@ -32,13 +32,13 @@ HELP: TYPED::
 { $example
 "USING: kernel math math.libm prettyprint typed ;
 IN: scratchpad
-
+<<
 TYPED:: quadratic-roots ( a: float b: float c: float -- q1: float q2: float )
     b neg
     b sq 4.0 a * c * - fsqrt
     [ + ] [ - ] 2bi
     [ 2.0 a * / ] bi@ ;
-
+>>
 1 0 -9/4 quadratic-roots [ . ] bi@"
 "1.5
 -1.5" } } ;
diff --git a/basis/ui/backend/gtk/gtk-docs.factor b/basis/ui/backend/gtk/gtk-docs.factor
index 83e214dd4f..2e436341cb 100644
--- a/basis/ui/backend/gtk/gtk-docs.factor
+++ b/basis/ui/backend/gtk/gtk-docs.factor
@@ -12,14 +12,14 @@ HELP: icon-data
 
 HELP: key-sym
 { $values
-  { "event" GdkEventKey }
-  { "sym/f" { $maybe string } }
+  { "keyval" GdkEventKey }
+  { "string/f" { $maybe string } }
   { "action?" boolean }
 } { $description "Gets the key symbol and action indicator from a " { $link GdkEventKey } " struct. If 'action?' is " { $link t } ", then the key is one of the special keys in " { $link codes } "." } ;
 
 HELP: on-configure
 { $values
-  { "win" alien }
+  { "window" alien }
   { "event" alien }
   { "user-data" alien }
   { "?" boolean }
diff --git a/basis/vocabs/metadata/metadata-docs.factor b/basis/vocabs/metadata/metadata-docs.factor
index 3fe93916b6..9081619e6c 100644
--- a/basis/vocabs/metadata/metadata-docs.factor
+++ b/basis/vocabs/metadata/metadata-docs.factor
@@ -39,7 +39,7 @@ ARTICLE: "vocabs.metadata" "Vocabulary metadata"
 ABOUT: "vocabs.metadata"
 
 HELP: vocab-file-lines
-{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "lines" { $maybe { $sequence "lines" } } } }
+{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "lines/f" { $maybe { $sequence "lines" } } } }
 { $description "Outputs the lines of the file named " { $snippet "name" } " from the vocabulary's directory, or " { $link f } " if the file does not exist." } ;
 
 HELP: set-vocab-file-lines
diff --git a/basis/wrap/words/words-docs.factor b/basis/wrap/words/words-docs.factor
index e3a77e127a..3c54dc4ffd 100644
--- a/basis/wrap/words/words-docs.factor
+++ b/basis/wrap/words/words-docs.factor
@@ -14,7 +14,7 @@ ARTICLE: "wrap.words" "Word object wrapping"
 } ;
 
 HELP: wrap-words
-{ $values { "words" { "a sequence of " { $instance wrapping-word } "s" } } { "line-max" integer } { "line-ideal" integer } { "lines" "a sequence of sequences of words" } }
+{ $values { "words" { "a sequence of " { $instance wrapping-word } "s" } } { "width" integer } { "lines" "a sequence of sequences of words" } }
 { $description "Divides the words into lines, where the sum of the lengths of the words on a line (not counting breaks at the end of the line) is at most the given maximum. The returned set of lines is optimized to minimize the square of the deviation of each line from the ideal width. It is not guaranteed to be the minimal number of lines. Every line except for the first one starts with a non-break, and every one but the last ends with a break." } ;
 
 HELP: wrapping-word
diff --git a/basis/wrap/wrap-docs.factor b/basis/wrap/wrap-docs.factor
index 0f6b7f5a94..fd4e345750 100644
--- a/basis/wrap/wrap-docs.factor
+++ b/basis/wrap/wrap-docs.factor
@@ -1,6 +1,6 @@
 ! Copyright (C) 2009 Daniel Ehrenberg
 ! See http://factorcode.org/license.txt for BSD license.
-USING: help.syntax help.markup strings math kernel ;
+USING: arrays help.markup help.syntax kernel math strings ;
 IN: wrap
 
 ABOUT: "wrap"
@@ -19,5 +19,5 @@ HELP: element
 } ;
 
 HELP: wrap
-{ $values { "elements" { $sequence element } } { "width" real } }
+{ $values { "elements" { $sequence element } } { "width" real } { "array" array } }
 { $description "Break the " { $snippet "elements" } " into lines such that the total width of each line tries to be less than " { $snippet "width" } " while attempting to minimize the raggedness represented by the amount of space at the end of each line. Returns an array of lines." } ;
diff --git a/core/alien/alien-docs.factor b/core/alien/alien-docs.factor
index 2d4caa5736..16a38fac40 100644
--- a/core/alien/alien-docs.factor
+++ b/core/alien/alien-docs.factor
@@ -95,7 +95,7 @@ HELP: c-ptr
 { $class-description "Class of objects consisting of aliens, byte arrays and " { $link f } ". These objects all can be used as values of " { $link pointer } " C types." } ;
 
 HELP: alien-invoke
-{ $values { "args..." "zero or more objects passed to the C function" } { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } { "return..." "the return value of the function, if not " { $link void } } }
+{ $values { "args..." "zero or more objects passed to the C function" } { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } { "varargs?" boolean } { "return..." "the return value of the function, if not " { $link void } } }
 { $description "Calls a C library function with the given name. Input parameters are taken from the data stack, and the return value is pushed on the data stack after the function returns. A return type of " { $link void } " indicates that no value is to be expected." }
 { $notes "C type names are documented in " { $link "c-types-specs" } "." }
 { $errors "Throws an " { $link callsite-not-compiled } " if the word calling " { $link alien-invoke } " was not compiled with the optimizing compiler." } ;
diff --git a/core/classes/tuple/tuple-docs.factor b/core/classes/tuple/tuple-docs.factor
index 4ee30d1d8b..b1d20a04d6 100644
--- a/core/classes/tuple/tuple-docs.factor
+++ b/core/classes/tuple/tuple-docs.factor
@@ -455,7 +455,7 @@ HELP: bad-superclass
 { $error-description "Thrown if an attempt is made to subclass a class that is not a tuple class, or a tuple class declared " { $link POSTPONE: final } "." } ;
 
 HELP: ?offset-of-slot
-{ $values { "name" string } { "tuple" tuple } { "n" { $maybe integer } } }
+{ $values { "name" string } { "tuple" tuple } { "n/f" { $maybe integer } } }
 { $description "Returns the offset of a tuple slot accessed by " { $snippet "name" } ", or " { $link f } " if no slot with that name." } ;
 
 HELP: offset-of-slot
diff --git a/core/kernel/kernel-docs.factor b/core/kernel/kernel-docs.factor
index 3f290bdea7..ad0009e95f 100644
--- a/core/kernel/kernel-docs.factor
+++ b/core/kernel/kernel-docs.factor
@@ -794,7 +794,7 @@ HELP: curried
 { curry curried compose prepose composed } related-words
 
 HELP: 2curry
-{ $values { "obj1" object } { "obj2" object } { "quot" callable } { "curry" curried } }
+{ $values { "obj1" object } { "obj2" object } { "quot" callable } { "curried" curried } }
 { $description "Outputs a " { $link callable } " which pushes " { $snippet "obj1" } " and " { $snippet "obj2" } " and then calls " { $snippet "quot" } "." }
 { $notes "This operation is efficient and does not copy the quotation." }
 { $examples
@@ -802,12 +802,12 @@ HELP: 2curry
 } ;
 
 HELP: 3curry
-{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quot" callable } { "curry" curried } }
+{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quot" callable } { "curried" curried } }
 { $description "Outputs a " { $link callable } " which pushes " { $snippet "obj1" } ", " { $snippet "obj2" } " and " { $snippet "obj3" } ", and then calls " { $snippet "quot" } "." }
 { $notes "This operation is efficient and does not copy the quotation." } ;
 
 HELP: with
-{ $values { "param" object } { "obj" object } { "quot" { $quotation ( param elt -- ... ) } } { "curry" curried } }
+{ $values { "param" object } { "obj" object } { "quot" { $quotation ( param elt -- ... ) } } { "curried" curried } }
 { $description "Partial application on the left. The following two lines are equivalent:"
     { $code "swap [ swap A ] curry B" }
     { $code "[ A ] with B" }
@@ -825,7 +825,7 @@ HELP: 2with
   { "param2" object }
   { "obj" object }
   { "quot" { $quotation ( param1 param2 elt -- ... ) } }
-  { "curry" curried }
+  { "curried" curried }
 }
 { $description "Partial application on the left of two parameters." } ;
 
@@ -842,7 +842,7 @@ HELP: compose
 } ;
 
 HELP: prepose
-{ $values { "quot1" callable } { "quot2" callable } { "compose" composed } }
+{ $values { "quot1" callable } { "quot2" callable } { "composed" composed } }
 { $description "Quotation composition. Outputs a " { $link callable } " which calls " { $snippet "quot2" } " followed by " { $snippet "quot1" } "." }
 { $notes "See " { $link compose } " for details." } ;
 
diff --git a/core/math/math-docs.factor b/core/math/math-docs.factor
index c37e788efa..236ba6f4cc 100644
--- a/core/math/math-docs.factor
+++ b/core/math/math-docs.factor
@@ -277,7 +277,7 @@ HELP: if-zero
 
 HELP: when-zero
 { $values
-     { "n" number } { "quot" "the first quotation of an " { $link if-zero } } }
+     { "n" number } { "quot" "the first quotation of an " { $link if-zero } } { "x" object } }
 { $description "Makes an implicit check if the number is zero. A zero is dropped and the " { $snippet "quot" } " is called." }
 { $examples "This word is equivalent to " { $link if-zero } " with an empty second quotation:"
     { $example
diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor
index 1c8dcf80c0..fbb65a9133 100644
--- a/core/sequences/sequences-docs.factor
+++ b/core/sequences/sequences-docs.factor
@@ -1210,12 +1210,12 @@ HELP: supremum
 { min max supremum infimum } related-words
 
 HELP: shortest
-{ $values { "seq" sequence } { "elt" object } }
-{ $description "Outputs the shortest element of " { $snippet "seq" } "." } ;
+{ $values { "seqs" sequence } { "elt" object } }
+{ $description "Outputs the shortest sequence from " { $snippet "seqs" } "." } ;
 
 HELP: longest
-{ $values { "seq" sequence } { "elt" object } }
-{ $description "Outputs the longest element of " { $snippet "seq" } "." } ;
+{ $values { "seqs" sequence } { "elt" object } }
+{ $description "Outputs the longest sequence from " { $snippet "seqs" } "." } ;
 
 { shortest longest } related-words
 
diff --git a/extra/ctags/ctags-docs.factor b/extra/ctags/ctags-docs.factor
index 64a645df64..c4312dcf48 100644
--- a/extra/ctags/ctags-docs.factor
+++ b/extra/ctags/ctags-docs.factor
@@ -20,7 +20,7 @@ HELP: write-ctags
 } ;
 
 HELP: ctags
-{ $values { "alist" "ctags" } }
+{ $values { "ctags" "alist" } }
 { $description "Make a sequence of ctags from " { $link all-words } ", sorted by word name." } ;
 
 ABOUT: "ctags"
diff --git a/extra/fuel/help/help-docs.factor b/extra/fuel/help/help-docs.factor
index 6cbdcc27cc..0aff60a5c7 100644
--- a/extra/fuel/help/help-docs.factor
+++ b/extra/fuel/help/help-docs.factor
@@ -6,7 +6,7 @@ HELP: article-parents
 { $description "All the parent articles for the article and ensures that the ancestor always is 'handbook'." } ;
 
 HELP:  get-article
-{ $values { "name" string } { "str" string } }
+{ $values { "name" string } { "element" string } }
 { $description "If an article and a vocab share name, we render the vocab instead." } ;
 
 HELP: find-word
diff --git a/extra/gpu/shaders/shaders-docs.factor b/extra/gpu/shaders/shaders-docs.factor
index e00defe626..f8d9d30aa2 100644
--- a/extra/gpu/shaders/shaders-docs.factor
+++ b/extra/gpu/shaders/shaders-docs.factor
@@ -31,6 +31,7 @@ HELP: <vertex-array-object>
   { "vertex-buffer" "a vertex buffer" }
   { "program-instance" program-instance }
   { "format" vertex-format }
+  { "vertex-array" vertex-array }
 }
 { $description "Creates a new vertex array object." } ;
 
diff --git a/extra/odbc/odbc-docs.factor b/extra/odbc/odbc-docs.factor
index 52a9ee8c48..6f1c6448bc 100644
--- a/extra/odbc/odbc-docs.factor
+++ b/extra/odbc/odbc-docs.factor
@@ -77,7 +77,7 @@ HELP: odbc-number-of-columns
 HELP: odbc-describe-column
 { $values
     { "statement" "an ODBC statement handle" }
-    { "n" "a column number starting from one" }
+    { "columnNumber" "a column number starting from one" }
     { "column" "a column object" }
 }
 { $description
@@ -88,7 +88,7 @@ HELP: odbc-describe-column
 HELP: odbc-get-field
 { $values
     { "statement" "an ODBC statement handle" }
-    { "column" "a column number starting from one or a <column> object" }
+    { "column!" "a column number starting from one or a <column> object" }
     { "field" "a <field> object" }
 }
 { $description
diff --git a/extra/successor/successor-docs.factor b/extra/successor/successor-docs.factor
index fad0a23d11..025ff47f38 100644
--- a/extra/successor/successor-docs.factor
+++ b/extra/successor/successor-docs.factor
@@ -6,7 +6,7 @@ USING: help.markup help.syntax successor strings ;
 IN: succesor
 
 HELP: successor
-{ $values { "str" string } }
+{ $values { "str" string } { "str'" string } }
 { $description
     "Returns the successor to " { $snippet "str" } ". The successor is calculated by incrementing characters starting from the rightmost alphanumeric (or the rightmost character if there are no alphanumerics) in the string. Incrementing a digit always results in another digit, and incrementing a letter results in another letter of the same case. "
     $nl
diff --git a/extra/trees/trees-docs.factor b/extra/trees/trees-docs.factor
index 5df07e4ef3..0a9efeaab1 100644
--- a/extra/trees/trees-docs.factor
+++ b/extra/trees/trees-docs.factor
@@ -177,14 +177,14 @@ HELP: first-key
 HELP: pop-tree-left
 { $values
     { "tree" tree }
-    { "pair/f" { $maybe pair } }
+    { "node/f" { $maybe pair } }
 }
 { $description "Removes and returns a key-value mapping associated with the lowest key in this map, or " { $link f } " if the map is empty." } ;
 
 HELP: pop-tree-right
 { $values
     { "tree" tree }
-    { "pair/f" { $maybe pair } }
+    { "node/f" { $maybe pair } }
 }
 { $description "Removes and returns a key-value mapping associated with the highest key in this map, or " { $link f } " if the map is empty." } ;
 
diff --git a/extra/ui/gadgets/charts/lines/lines-docs.factor b/extra/ui/gadgets/charts/lines/lines-docs.factor
index 8fc9cf1f87..bde78cc9ee 100644
--- a/extra/ui/gadgets/charts/lines/lines-docs.factor
+++ b/extra/ui/gadgets/charts/lines/lines-docs.factor
@@ -57,6 +57,12 @@ $nl
 
 HELP: y-at
 { $description "Given two points on a straight line and an " { $snippet "x" } " coordinate, calculate the " { $snippet "y" } " coordinate at " { $snippet "x" } " on that line." }
+{ $values
+    { "x" object }
+    { "point1" object }
+    { "point2" object }
+    { "y" object }
+}
 { $examples
     { $example
         "USING: ui.gadgets.charts.lines.private prettyprint ;"
@@ -77,6 +83,12 @@ HELP: y-at
 
 HELP: calc-x
 { $description "Given the " { $snippet "slope" } " of a line and a random " { $snippet "point" } " belonging to that line, calculate the " { $snippet "x" } " coordinate corresponding to the given " { $snippet "y" } "." }
+{ $values
+    { "slope" object }
+    { "y" object }
+    { "point" object }
+    { "x" object }
+}
 { $examples
     { $example
         "USING: ui.gadgets.charts.lines.private prettyprint ;"
@@ -92,6 +104,12 @@ HELP: calc-x
 
 HELP: calc-y
 { $description "Given the " { $snippet "slope" } " of a line and a random " { $snippet "point" } " belonging to that line, calculate the " { $snippet "y" } " coordinate corresponding to the given " { $snippet "x" } "." }
+{ $values
+    { "slope" object }
+    { "x" object }
+    { "point" object }
+    { "y" object }
+}
 { $examples
     { $example
         "USING: ui.gadgets.charts.lines.private prettyprint ;"
@@ -107,6 +125,11 @@ HELP: calc-y
 
 HELP: calc-line-slope
 { $description "Given the two points belonging to a straight line, calculate the " { $snippet "slope" } " of the line, assuming the line equation is " { $snippet "y(x) = slope * x + b" } "."
+{ $values
+    { "point1" object }
+    { "point2" object }
+    { "slope" object }
+}
 $nl
 "The formula for the calculation is " { $snippet "slope = (y1-y2) / (x1-x2)" } ", therefore it'll throw a division by zero error if both points have the same " { $snippet "x" } " coordinate." }
 { $examples
-- 
2.34.1