Update documentation for new help lint check

basis/calendar/calendar-docs.factor

@@ -309,7 +309,7 @@ HELP: time-
 } ;
 
 HELP: convert-timezone
-{ $values { "timestamp" timestamp } { "duration" duration } { "timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "duration" duration } { "timestamp'" timestamp } }
 { $description "Converts the " { $snippet "timestamp" } "'s " { $snippet "gmt-offset" } " to the GMT offset represented by the " { $snippet "duration" } "." }
 { $examples
     { $example "USING: accessors calendar prettyprint ;"
@@ -319,7 +319,7 @@ HELP: convert-timezone
 } ;
 
 HELP: >local-time
-{ $values { "timestamp" timestamp } { "timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 { $description "Converts the " { $snippet "timestamp" } " to the timezone of your computer." }
 { $examples
     { $example "USING: accessors calendar kernel prettyprint ;"
@@ -329,7 +329,7 @@ HELP: >local-time
 } ;
 
 HELP: >gmt
-{ $values { "timestamp" timestamp } { "timestamp" timestamp } }
+{ $values { "timestamp" timestamp } { "timestamp'" timestamp } }
 { $description "Converts the " { $snippet "timestamp" } " to the GMT timezone." }
 { $examples
     { $example "USING: accessors calendar kernel prettyprint ;"

basis/calendar/calendar.factor

@@ -316,15 +316,15 @@ M: duration <=> [ duration>years ] compare ;
 
 GENERIC: time- ( time1 time2 -- time3 )
 
-: convert-timezone ( timestamp duration -- timestamp )
+: convert-timezone ( timestamp duration -- timestamp' )
     over gmt-offset>> over = [ drop ] [
         [ over gmt-offset>> time- time+ ] keep >>gmt-offset
     ] if ;
 
-: >local-time ( timestamp -- timestamp )
+: >local-time ( timestamp -- timestamp' )
     gmt-offset-duration convert-timezone ;
 
-: >gmt ( timestamp -- timestamp )
+: >gmt ( timestamp -- timestamp' )
     instant convert-timezone ;
 
 M: timestamp <=> ( ts1 ts2 -- n )

basis/compression/lzw/lzw-docs.factor

@@ -20,7 +20,6 @@ HELP: tiff-lzw-uncompress
 
 HELP: lzw-read
 { $values
-    { "lzw" lzw }
     { "lzw" lzw } { "n" integer }
 }
 { $description "Read the next LZW code." } ;
@@ -48,7 +47,6 @@ HELP: code-space-full?
 HELP: reset-lzw-uncompress
 { $values
     { "lzw" lzw }
-    { "lzw" lzw }
 }
 { $description "Reset the LZW uncompressor state (either at initialization time or immediately after receiving a Clear Code). " } ;
 

basis/db/tuples/tuples-docs.factor

@@ -51,7 +51,7 @@ HELP: <insert-user-assigned-statement>
 HELP: <select-by-slots-statement>
 { $values
      { "tuple" tuple } { "class" class }
-     { "tuple" tuple } }
+     { "statement" tuple } }
 { $description "A database-specific hook for generating the SQL for a select statement." } ;
 
 HELP: <update-tuple-statement>

basis/db/tuples/tuples.factor

@@ -14,7 +14,7 @@ HOOK: <insert-db-assigned-statement> db-connection ( class -- object )
 HOOK: <insert-user-assigned-statement> db-connection ( class -- object )
 HOOK: <update-tuple-statement> db-connection ( class -- object )
 HOOK: <delete-tuples-statement> db-connection ( tuple class -- object )
-HOOK: <select-by-slots-statement> db-connection ( tuple class -- tuple )
+HOOK: <select-by-slots-statement> db-connection ( tuple class -- statement )
 HOOK: <count-statement> db-connection ( query -- statement )
 HOOK: query>statement db-connection ( query -- statement )
 HOOK: insert-tuple-set-key db-connection ( tuple statement -- )

basis/dlists/dlists-docs.factor

@@ -48,7 +48,7 @@ HELP: dlist-find
 } ;
 
 HELP: dlist-filter
-{ $values { "dlist" { $link dlist } } { "quot" quotation } { "dlist" { $link dlist } } }
+{ $values { "dlist" { $link dlist } } { "quot" quotation } { "dlist'" { $link dlist } } }
 { $description "Applies the quotation to each element of the " { $link dlist } " in turn, removing the corresponding nodes if the quotation returns " { $link f } "." }
 { $side-effects { "dlist" } } ;
 

basis/dlists/dlists.factor

@@ -157,7 +157,7 @@ M: dlist clear-deque ( dlist -- )
 
 : 1dlist ( obj -- dlist ) <dlist> [ push-front ] keep ;
 
-: dlist-filter ( dlist quot -- dlist )
+: dlist-filter ( dlist quot -- dlist' )
     over [ '[ dup obj>> @ [ drop ] [ _ delete-node ] if ] dlist-each-node ] keep ; inline
 
 M: dlist clone

basis/images/normalization/normalization-docs.factor

@@ -6,14 +6,14 @@ IN: images.normalization
 HELP: normalize-image
 { $values
     { "image" image }
-    { "image" image }
+    { "image'" image }
 }
 { $description "Converts the image to RGBA with ubyte-components. If the image is upside-down, it will be flipped right side up such that the 1st byte in the bitmap slot's byte array corresponds to the first color component of the pixel in the upper-left corner of the image." } ;
 
 HELP: reorder-components
 { $values
     { "image" image } { "component-order" component-order }
-    { "image" image }
+    { "image'" image }
 }
 { $description "Convert the bitmap in " { $snippet "image" } " such that the pixel sample layout corresponds to " { $snippet "component-order" } ". If the destination layout cannot find a corresponding value from the source layout, the value " { $snippet "255" } " will be substituted for that byte." }
 { $warning "The image's " { $snippet "component-type" } " will be changed to " { $snippet "ubyte-components" } " if it is not already in that format."

basis/images/normalization/normalization.factor

@@ -55,7 +55,7 @@ M: ushort-components normalize-component-type*
 M: ubyte-components normalize-component-type*
     drop ;
 
-: normalize-scan-line-order ( image -- image )
+: normalize-scan-line-order ( image -- image' )
     dup upside-down?>> [
         dup dim>> first 4 * '[
             _ <groups> reverse concat
@@ -71,14 +71,14 @@ M: ubyte-components normalize-component-type*
 
 PRIVATE>
 
-: reorder-components ( image component-order -- image )
+: reorder-components ( image component-order -- image' )
     [
         dup component-type>> '[ _ normalize-component-type* ] change-bitmap
         dup component-order>>
     ] dip
     validate-request [ (reorder-components) ] keep >>component-order ;
 
-: normalize-image ( image -- image )
+: normalize-image ( image -- image' )
     [ >byte-array ] change-bitmap
     RGBA reorder-components
     normalize-scan-line-order ;

basis/lists/lazy/lazy-docs.factor

@@ -144,7 +144,7 @@ HELP: lcomp
 { $description "Get the cartesian product of the lists in " { $snippet "list" } " and call " { $snippet "quot" } " call with each element from the cartesian product on the stack, the result of which is returned in the final " { $snippet "list" } "." } ;
 
 HELP: lcomp*
-{ $values { "list" "a list of lists" } { "guards" "a sequence of quotations with stack effect ( seq -- bool )" } { "quot" { $quotation "( seq -- X )" } } { "list" "the resulting list" } { "result" "a list" } }
+{ $values { "list" "a list of lists" } { "guards" "a sequence of quotations with stack effect ( seq -- bool )" } { "quot" { $quotation "( seq -- X )" } } { "result" "a list" } }
 { $description "Get the cartesian product of the lists in " { $snippet "list" } ", filter it by applying each guard quotation to it and call " { $snippet "quot" } " call with each element from the remaining cartesian product items on the stack, the result of which is returned in the final " { $snippet "list" } "." }
 { $examples
   { $code "{ 1 2 3 } >list { 4 5 6 } >list 2list { [ first odd? ] } [ first2 + ] lcomp*" }

basis/math/bitwise/bitwise-docs.factor

@@ -88,10 +88,10 @@ HELP: bit-count
 
 HELP: bitroll-32
 { $values
-     { "n" integer } { "s" integer }
-     { "n'" integer }
+     { "m" integer } { "s" integer }
+     { "n" integer }
 }     
-{ $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 32 bits." }
+{ $description "Rolls the number " { $snippet "m" } " by " { $snippet "s" } " bits to the left, wrapping around after 32 bits." }
 { $examples 
     { $example "USING: math.bitwise prettyprint ;"
                "HEX: 1 10 bitroll-32 .h"
@@ -105,10 +105,10 @@ HELP: bitroll-32
 
 HELP: bitroll-64
 { $values
-     { "n" integer } { "s" "a shift integer" }
-     { "n'" integer }
+     { "m" integer } { "s" "a shift integer" }
+     { "n" integer }
 }
-{ $description "Rolls the number " { $snippet "n" } " by " { $snippet "s" } " bits to the left, wrapping around after 64 bits." }
+{ $description "Rolls the number " { $snippet "m" } " by " { $snippet "s" } " bits to the left, wrapping around after 64 bits." }
 { $examples 
     { $example "USING: math.bitwise prettyprint ;"
                "HEX: 1 10 bitroll-64 .h"
@@ -226,10 +226,10 @@ HELP: odd-parity?
 
 HELP: on-bits
 { $values
-     { "n" integer }
      { "m" integer }
+     { "n" integer }
 }
-{ $description "Returns an integer with " { $snippet "n" } " bits set." }
+{ $description "Returns an integer with " { $snippet "m" } " bits set." }
 { $examples
     { $example "USING: math.bitwise kernel prettyprint ;"
         "6 on-bits .h"
@@ -274,7 +274,7 @@ HELP: set-bit
 
 HELP: shift-mod
 { $values
-     { "n" integer } { "s" integer } { "w" integer }
+     { "m" integer } { "s" integer } { "w" integer }
      { "n" integer }
 }
 { $description "Calls " { $link shift } " on " { $snippet "n" } " and " { $snippet "s" } ", wrapping the result to " { $snippet "w" } " bits." } ;
@@ -307,8 +307,8 @@ HELP: unmask?
 
 HELP: w*
 { $values
-     { "int" integer } { "int" integer }
-     { "int" integer }
+     { "x" integer } { "y" integer }
+     { "z" integer }
 }
 { $description "Multiplies two integers and wraps the result to 32 bits." }
 { $examples
@@ -320,8 +320,8 @@ HELP: w*
 
 HELP: w+
 { $values
-     { "int" integer } { "int" integer }
-     { "int" integer }
+     { "x" integer } { "y" integer }
+     { "z" integer }
 }
 { $description "Adds two integers and wraps the result to 32 bits." }
 { $examples
@@ -333,8 +333,8 @@ HELP: w+
 
 HELP: w-
 { $values
-     { "int" integer } { "int" integer }
-     { "int" integer }
+     { "x" integer } { "y" integer }
+     { "z" integer }
 }
 { $description "Subtracts two integers and wraps the result to 32 bits." }
 { $examples

basis/math/bitwise/bitwise.factor

@@ -17,29 +17,32 @@ IN: math.bitwise
 : wrap ( m n -- m' ) 1 - bitand ; inline
 : bits ( m n -- m' ) 2^ wrap ; inline
 : mask-bit ( m n -- m' ) 2^ mask ; inline
-: on-bits ( n -- m ) 2^ 1 - ; inline
+: on-bits ( m -- n ) 2^ 1 - ; inline
 : toggle-bit ( m n -- m' ) 2^ bitxor ; inline
-
-: shift-mod ( n s w -- n )
-    [ shift ] dip 2^ wrap ; inline
+: >signed ( x n -- y ) 2dup neg 1 + shift 1 = [ 2^ - ] [ drop ] if ;
+: >odd ( m -- n ) 0 set-bit ; foldable
+: >even ( m -- n ) 0 clear-bit ; foldable
+: next-even ( m -- n ) >even 2 + ; foldable
+: next-odd ( m -- n ) dup even? [ 1 + ] [ 2 + ] if ; foldable
+: shift-mod ( m s w -- n ) [ shift ] dip 2^ wrap ; inline
 
 : bitroll ( x s w -- y )
     [ wrap ] keep
     [ shift-mod ] [ [ - ] keep shift-mod ] 3bi bitor ; inline
 
-: bitroll-32 ( n s -- n' ) 32 bitroll ; inline
+: bitroll-32 ( m s -- n ) 32 bitroll ; inline
 
-: bitroll-64 ( n s -- n' ) 64 bitroll ; inline
+: bitroll-64 ( m s -- n ) 64 bitroll ; inline
 
 ! 32-bit arithmetic
-: w+ ( int int -- int ) + 32 bits ; inline
-: w- ( int int -- int ) - 32 bits ; inline
-: w* ( int int -- int ) * 32 bits ; inline
+: w+ ( x y -- z ) + 32 bits ; inline
+: w- ( x y -- z ) - 32 bits ; inline
+: w* ( x y -- z ) * 32 bits ; inline
 
 ! 64-bit arithmetic
-: W+ ( int int -- int ) + 64 bits ; inline
-: W- ( int int -- int ) - 64 bits ; inline
-: W* ( int int -- int ) * 64 bits ; inline
+: W+ ( x y -- z ) + 64 bits ; inline
+: W- ( x y -- z ) - 64 bits ; inline
+: W* ( x y -- z ) * 64 bits ; inline
 
 ! flags
 MACRO: flags ( values -- )
@@ -117,17 +120,6 @@ M: object bit-count
     [ >c-ptr ] [ byte-length ] bi <direct-uchar-array>
     byte-array-bit-count ;
 
-: >signed ( x n -- y )
-    2dup neg 1 + shift 1 = [ 2^ - ] [ drop ] if ;
-
-: >odd ( n -- int ) 0 set-bit ; foldable
-
-: >even ( n -- int ) 0 clear-bit ; foldable
-
-: next-even ( m -- n ) >even 2 + ; foldable
-
-: next-odd ( m -- n ) dup even? [ 1 + ] [ 2 + ] if ; foldable
-
 : even-parity? ( obj -- ? ) bit-count even? ;
 
 : odd-parity? ( obj -- ? ) bit-count odd? ;

basis/math/combinatorics/combinatorics-docs.factor

@@ -26,7 +26,7 @@ HELP: nCk
 } ;
 
 HELP: permutation
-{ $values { "n" "a non-negative integer" } { "seq" sequence } { "seq" sequence } }
+{ $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
@@ -37,7 +37,7 @@ HELP: permutation
 } ;
 
 HELP: all-permutations
-{ $values { "seq" sequence } { "seq" sequence } }
+{ $values { "seq" sequence } { "seq'" sequence } }
 { $description "Outputs a sequence containing all permutations of " { $snippet "seq" } " in lexicographical order." }
 { $examples
     { $example "USING: math.combinatorics prettyprint ;"
@@ -60,7 +60,7 @@ HELP: inverse-permutation
 } ;
 
 HELP: combination
-{ $values { "m" "a non-negative integer" } { "seq" sequence } { "k" "a non-negative integer" } { "seq" sequence } }
+{ $values { "m" "a non-negative integer" } { "seq" sequence } { "k" "a non-negative integer" } { "seq'" sequence } }
 { $description "Outputs the " { $snippet "mth" } " lexicographical combination of " { $snippet "seq" } " choosing " { $snippet "k" } " elements." }
 { $notes "Combinations are 0-based and a bounds error will be thrown if " { $snippet "m" } " is larger than " { $snippet "seq length k nCk" } "." }
 { $examples
@@ -71,7 +71,7 @@ HELP: combination
 } ;
 
 HELP: all-combinations
-{ $values { "seq" sequence } { "k" "a non-negative integer" } { "seq" sequence } }
+{ $values { "seq" sequence } { "k" "a non-negative integer" } { "seq'" sequence } }
 { $description "Outputs a sequence containing all combinations of " { $snippet "seq" } " choosing " { $snippet "k" } " elements, in lexicographical order." }
 { $examples
     { $example "USING: math.combinatorics prettyprint ;"

basis/math/combinatorics/combinatorics.factor

@@ -42,10 +42,10 @@ PRIVATE>
 
 PRIVATE>
 
-: permutation ( n seq -- seq )
+: permutation ( n seq -- seq' )
     [ permutation-indices ] keep nths ;
 
-: all-permutations ( seq -- seq )
+: all-permutations ( seq -- seq' )
     [ length factorial iota ] keep
     '[ _ permutation ] map ;
 
@@ -118,10 +118,10 @@ PRIVATE>
 : map>assoc-combinations ( seq k quot exemplar -- )
     [ combinations-quot ] dip map>assoc ; inline
 
-: combination ( m seq k -- seq )
+: combination ( m seq k -- seq' )
     <combo> apply-combination ;
 
-: all-combinations ( seq k -- seq )
+: all-combinations ( seq k -- seq' )
     [ ] combinations-quot map ;
 
 : reduce-combinations ( seq k identity quot -- result )

basis/math/polynomials/polynomials-docs.factor

@@ -36,12 +36,12 @@ HELP: p=
 { $examples { $example "USING: math.polynomials prettyprint ;" "{ 0 1 } { 0 1 0 } p= ." "t" } } ;
 
 HELP: ptrim
-{ $values { "p" "a polynomial" } { "p" "a polynomial" } }
+{ $values { "p" "a polynomial" } { "q" "a polynomial" } }
 { $description "Trims excess zeros from a polynomial." }
 { $examples { $example "USING: math.polynomials prettyprint ;" "{ 0 1 0 0 } ptrim ." "{ 0 1 }" } } ;
 
 HELP: 2ptrim
-{ $values { "p" "a polynomial" } { "q" "a polynomial" } { "p" "a polynomial" } { "q" "a polynomial" } }
+{ $values { "p" "a polynomial" } { "q" "a polynomial" } { "p'" "a polynomial" } { "q'" "a polynomial" } }
 { $description "Trims excess zeros from two polynomials." }
 { $examples { $example "USING: kernel math.polynomials prettyprint ;" "{ 0 1 0 0 } { 1 0 0 } 2ptrim [ . ] bi@" "{ 0 1 }\n{ 1 }" } } ;
 
@@ -61,7 +61,7 @@ HELP: n*p
 { $examples { $example "USING: math.polynomials prettyprint ;" "4 { 3 0 1 } n*p ." "{ 12 0 4 }" } } ;
 
 HELP: pextend-conv
-{ $values { "p" "a polynomial" } { "q" "a polynomial" } { "p" "a polynomial" } { "q" "a polynomial" } }
+{ $values { "p" "a polynomial" } { "q" "a polynomial" } { "p'" "a polynomial" } { "q'" "a polynomial" } }
 { $description "Convulution, extending to " { $snippet "p_m + q_n - 1" } "." }
 { $examples { $example "USING: kernel math.polynomials prettyprint ;" "{ 1 0 1 } { 0 1 } pextend-conv [ . ] bi@" "V{ 1 0 1 0 }\nV{ 0 1 0 0 }" } } ;
 

basis/math/polynomials/polynomials.factor

@@ -20,15 +20,15 @@ PRIVATE>
 
 : p= ( p q -- ? ) pextend = ;
 
-: ptrim ( p -- p )
+: ptrim ( p -- q )
     dup length 1 = [ [ zero? ] trim-tail ] unless ;
 
-: 2ptrim ( p q -- p q ) [ ptrim ] bi@ ;
+: 2ptrim ( p q -- p' q' ) [ ptrim ] bi@ ;
 : p+ ( p q -- r ) pextend v+ ;
 : p- ( p q -- r ) pextend v- ;
 : n*p ( n p -- n*p ) n*v ;
 
-: pextend-conv ( p q -- p q )
+: pextend-conv ( p q -- p' q' )
     2dup [ length ] bi@ + 1 - 2pad-tail [ >vector ] bi@ ;
 
 : p* ( p q -- r )

basis/math/quaternions/quaternions-docs.factor

@@ -30,7 +30,7 @@ HELP: q/
 { $examples { $example "USING: math.quaternions prettyprint ;" "{ 0 0 0 1 } { 0 0 1 0 } q/ ." "{ 0 1 0 0 }" } } ;
 
 HELP: q*n
-{ $values { "q" "a quaternion" } { "n" real } { "q" "a quaternion" } }
+{ $values { "q" "a quaternion" } { "n" real } { "r" "a quaternion" } }
 { $description "Multiplies each element of " { $snippet "q" } " by real value " { $snippet "n" } "." }
 { $notes "To multiply a quaternion with a complex value, use " { $link c>q } " " { $link q* } "." } ;
 

basis/math/quaternions/quaternions.factor

@@ -1,4 +1,4 @@
-! Copyright (C) 2005, 2007 Slava Pestov.
+! Copyright (C) 2005, 2010 Joe Groff, Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: arrays combinators kernel locals math math.functions
 math.libm math.order math.vectors sequences ;
@@ -35,10 +35,10 @@ M: object qconjugate ( u -- u' )
 : q/ ( u v -- u/v )
     qrecip q* ; inline
 
-: n*q ( q n -- q )
+: n*q ( q n -- r )
     v*n ; inline
 
-: q*n ( q n -- q )
+: q*n ( q n -- r )
     v*n ; inline
 
 : n>q ( n -- q )

basis/math/statistics/statistics-docs.factor

@@ -87,7 +87,6 @@ HELP: histogram
 HELP: histogram!
 { $values
     { "hashtable" hashtable } { "seq" sequence }
-    { "hashtable" hashtable }
 }
 { $examples 
     { $example "! Count the number of times the elements of two sequences appear."
@@ -128,7 +127,6 @@ HELP: sequence>assoc
 HELP: sequence>assoc!
 { $values
     { "assoc" assoc } { "seq" sequence } { "quot" quotation }
-    { "assoc" assoc }
 }
 { $examples 
     { $example "! Iterate over a sequence and add the counts to an existing assoc"

basis/opengl/shaders/shaders-docs.factor

@@ -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" } { "shader" "a new " { $link gl-shader } } { "log" string } }
+{ $values { "shader" "A " { $link gl-shader } " object" } { "log" string } }
 { $description "Retrieves the info log for " { $snippet "shader" } ", including any errors or warnings generated in compiling the shader object." } ;
 
 HELP: gl-program

basis/random/random-docs.factor

@@ -75,7 +75,7 @@ HELP: with-system-random
 HELP: randomize
 { $values
      { "seq" sequence }
-     { "seq" sequence }
+     { "randomized" sequence }
 }
 { $description "Randomizes a sequence in-place with the Fisher-Yates algorithm and returns the sequence." } ;
 

basis/random/random.factor

@@ -67,7 +67,7 @@ M: sequence random
     [ [ random ] [ 1 - ] bi [ pick exchange ] keep ]
     while drop ;
 
-: randomize ( seq -- seq ) 
+: randomize ( seq -- randomized )
     dup length randomize-n-last ;
 
 ERROR: too-many-samples seq n ;

basis/roman/roman-docs.factor

@@ -39,7 +39,7 @@ HELP: roman>
 { >roman >ROMAN roman> } related-words
 
 HELP: roman+
-{ $values { "x" string } { "x" string } { "x" string } }
+{ $values { "x" string } { "y" string } { "z" string } }
 { $description "Adds two Roman numerals." }
 { $examples 
     { $example "USING: io roman ;"
@@ -49,7 +49,7 @@ HELP: roman+
 } ;
 
 HELP: roman-
-{ $values { "x" string } { "x" string } { "x" string } }
+{ $values { "x" string } { "y" string } { "z" string } }
 { $description "Subtracts two Roman numerals." }
 { $examples 
     { $example "USING: io roman ;"
@@ -61,7 +61,7 @@ HELP: roman-
 { roman+ roman- } related-words
 
 HELP: roman*
-{ $values { "x" string } { "x" string } { "x" string } }
+{ $values { "x" string } { "y" string } { "z" string } }
 { $description "Multiplies two Roman numerals." }
 { $examples 
     { $example "USING: io roman ;"
@@ -71,7 +71,7 @@ HELP: roman*
 } ;
 
 HELP: roman/i
-{ $values { "x" string } { "x" string } { "x" string } }
+{ $values { "x" string } { "y" string } { "z" string } }
 { $description "Computes the integer division of two Roman numerals." }
 { $examples 
     { $example "USING: io roman ;"
@@ -81,7 +81,7 @@ HELP: roman/i
 } ;
 
 HELP: roman/mod
-{ $values { "x" string } { "x" string } { "x" string } { "x" string } }
+{ $values { "x" string } { "y" string } { "z" string } { "w" string } }
 { $description "Computes the quotient and remainder of two Roman numerals." }
 { $examples 
     { $example "USING: kernel io roman ;"

basis/roman/roman.factor

@@ -2,8 +2,9 @@
 ! See http://factorcode.org/license.txt for BSD license.
 USING: accessors arrays assocs effects fry generalizations
 grouping kernel lexer macros math math.order math.vectors
-namespaces parser quotations sequences sequences.private
-splitting.monotonic stack-checker strings unicode.case words ;
+namespaces parser effects.parser quotations sequences
+sequences.private splitting.monotonic stack-checker strings
+unicode.case words ;
 IN: roman
 
 <PRIVATE
@@ -58,14 +59,14 @@ PRIVATE>
 SYNTAX: ROMAN-OP:
     scan-word [ name>> "roman" prepend create-in ] keep
     1quotation '[ _ binary-roman-op ]
-    dup infer define-declared ;
+    complete-effect define-declared ;
 
 >>
 
-ROMAN-OP: +
-ROMAN-OP: -
-ROMAN-OP: *
-ROMAN-OP: /i
-ROMAN-OP: /mod
+ROMAN-OP: + ( x y -- z )
+ROMAN-OP: - ( x y -- z )
+ROMAN-OP: * ( x y -- z )
+ROMAN-OP: /i ( x y -- z )
+ROMAN-OP: /mod ( x y -- z w )
 
 SYNTAX: ROMAN: scan roman> suffix! ;

basis/sequences/deep/deep-docs.factor

@@ -31,7 +31,7 @@ HELP: flatten
 { $description "Creates a sequence of all of the leaf nodes (non-sequence nodes, but including strings and numbers) in the object." } ;
 
 HELP: deep-map!
-{ $values { "obj" object } { "quot" { $quotation "( elt -- newelt )" } } { "obj" object } }
+{ $values { "obj" object } { "quot" { $quotation "( elt -- newelt )" } } }
 { $description "Modifies each sub-node of an object in place, in preorder, and returns that object." }
 { $see-also map! } ;
 

basis/ui/gadgets/worlds/worlds-docs.factor

@@ -33,7 +33,7 @@ HELP: set-gl-context
 { $description "Selects an OpenGL context to be the implicit destination for subsequent GL rendering calls. This word is called automatically by the UI before drawing a " { $link world } "." } ;
 
 HELP: window-resource
-{ $values { "resource" disposable } { "resource" disposable } }
+{ $values { "resource" disposable } }
 { $description "Marks " { $snippet "resource" } " to be destroyed with " { $link dispose } " when the window with the currently active OpenGL context (set by " { $link set-gl-context } ") is closed. " { $snippet "resource" } " is left unmodified at the top of the stack." } ;
 
 HELP: flush-gl-context

basis/xml-rpc/xml-rpc-docs.factor

@@ -49,7 +49,7 @@ HELP: rpc-fault
 
 HELP: post-rpc
 { $values { "rpc" "an XML-RPC input tuple" } { "url" "a URL" }
-    { "rpc" "an XML-RPC output tuple" } }
+    { "rpc'" "an XML-RPC output tuple" } }
 { $description "posts an XML-RPC document to the specified URL, receives the response and parses it as XML-RPC, returning the tuple" } ;
 
 ARTICLE: { "xml-rpc" "intro" } "XML-RPC"

basis/xml-rpc/xml-rpc.factor

@@ -186,7 +186,7 @@ TAG: array xml>item
 
 PRIVATE>
 
-: post-rpc ( rpc url -- rpc )
+: post-rpc ( rpc url -- rpc' )
     ! This needs to do something in the event of an error
     rpc-post-request http-request nip string>xml receive-rpc ;
 

basis/xml/traversal/traversal-docs.factor

@@ -58,7 +58,7 @@ HELP: children-tags
 { $see-also first-child-tag } ;
 
 HELP: first-child-tag
-{ $values { "tag" "an XML tag or document" } { "tag" tag } }
+{ $values { "tag" "an XML tag or document" } { "child" tag } }
 { $description "Returns the first child of the given tag that is a tag." }
 { $see-also children-tags } ;
 

basis/xml/traversal/traversal.factor

@@ -18,7 +18,7 @@ IN: xml.traversal
 : children-tags ( tag -- sequence )
     children>> [ tag? ] filter ;
 
-: first-child-tag ( tag -- tag )
+: first-child-tag ( tag -- child )
     children>> [ tag? ] find nip ;
 
 : tag-named? ( name elem -- ? )

core/kernel/kernel-docs.factor

@@ -708,7 +708,7 @@ HELP: 3curry
 { $notes "This operation is efficient and does not copy the quotation." } ;
 
 HELP: with
-{ $values { "param" object } { "obj" object } { "quot" { $quotation "( param elt -- ... )" } } { "obj" object } { "curry" curry } }
+{ $values { "param" object } { "obj" object } { "quot" { $quotation "( param elt -- ... )" } } { "curry" curry } }
 { $description "Partial application on the left. The following two lines are equivalent:"
     { $code "swap [ swap A ] curry B" }
     { $code "[ A ] with B" }

core/parser/parser-docs.factor

@@ -177,7 +177,7 @@ HELP: parse-lines
 { $errors "Throws a " { $link lexer-error } " if the input is malformed." } ;
 
 HELP: parse-base
-{ $values { "parsed" integer } { "base" "an integer between 2 and 36" } { "parsed" integer } }
+{ $values { "parsed" integer } { "base" "an integer between 2 and 36" } }
 { $description "Reads an integer in a specific numerical base from the parser input." }
 $parsing-note ;
 

core/sequences/sequences-docs.factor

@@ -296,7 +296,7 @@ $nl
 } ;
 
 HELP: accumulate!
-{ $values { "seq" sequence } { "identity" object } { "quot" { $quotation "( prev elt -- next )" } } { "final" "the final result" } { "seq" sequence } }
+{ $values { "seq" sequence } { "identity" object } { "quot" { $quotation "( prev elt -- next )" } } { "final" "the final result" } }
 { $description "Combines successive elements of the sequence using a binary operation, and outputs the original sequence of intermediate results, together with the final result."
 $nl
 "The first element of the new sequence is " { $snippet "identity" } ". Then, on the first iteration, the two inputs to the quotation are " { $snippet "identity" } ", and the first element of the old sequence. On successive iterations, the first input is the result of the previous iteration, and the second input is the corresponding element of the old sequence."
@@ -344,7 +344,7 @@ HELP: change-nth
 { $side-effects "seq" } ;
 
 HELP: map!
-{ $values { "seq" "a mutable sequence" } { "quot" { $quotation "( old -- new )" } } { "seq" "a mutable sequence" } }
+{ $values { "seq" "a mutable sequence" } { "quot" { $quotation "( old -- new )" } } }
 { $description "Applies the quotation to each element yielding a new element, storing the new elements back in the original sequence. Returns the original sequence." }
 { $errors "Throws an error if the sequence is immutable, or the sequence cannot hold elements of the type output by " { $snippet "quot" } "." }
 { $side-effects "seq" } ;
@@ -442,7 +442,7 @@ HELP: filter-as
 { $description "Applies the quotation to each element in turn, and outputs a new sequence of the same type as " { $snippet "exemplar" } " containing the elements of the original sequence for which the quotation output a true value." } ;
 
 HELP: filter!
-{ $values { "seq" "a resizable mutable sequence" } { "quot" { $quotation "( elt -- ? )" } } { "seq" "a resizable mutable sequence" } }
+{ $values { "seq" "a resizable mutable sequence" } { "quot" { $quotation "( elt -- ? )" } } }
 { $description "Applies the quotation to each element in turn, and removes elements for which the quotation outputs a false value." }
 { $side-effects "seq" } ;
 
@@ -503,19 +503,19 @@ HELP: move
 { $side-effects "seq" } ;
 
 HELP: remove!
-{ $values { "elt" object } { "seq" "a resizable mutable sequence" } { "elt" object } }
+{ $values { "elt" object } { "seq" "a resizable mutable sequence" } }
 { $description "Removes all elements equal to " { $snippet "elt" } " from " { $snippet "seq" } " and returns " { $snippet "seq" } "." }
 { $notes "This word uses equality comparison (" { $link = } ")." }
 { $side-effects "seq" } ;
 
 HELP: remove-eq!
-{ $values { "elt" object } { "seq" "a resizable mutable sequence" } { "seq" "a resizable mutable sequence" } }
+{ $values { "elt" object } { "seq" "a resizable mutable sequence" } }
 { $description "Outputs a new sequence containing all elements of the input sequence except the given element." }
 { $notes "This word uses identity comparison (" { $link eq? } ")." }
 { $side-effects "seq" } ;
 
 HELP: remove-nth!
-{ $values { "n" "a non-negative integer" } { "seq" "a resizable mutable sequence" } { "seq" "a resizable mutable sequence" } }
+{ $values { "n" "a non-negative integer" } { "seq" "a resizable mutable sequence" } }
 { $description "Removes the " { $snippet "n" } "th element from the sequence, shifting all other elements down and reducing its length by one." }
 { $side-effects "seq" } ;
 
@@ -540,7 +540,7 @@ HELP: suffix
 } ;
 
 HELP: suffix!
-{ $values { "seq" sequence } { "elt" object } { "seq" sequence } }
+{ $values { "seq" sequence } { "elt" object } }
 { $description "Modifiers a sequence in-place by adding " { $snippet "elt" } " to the end of " { $snippet "seq" } ". Outputs " { $snippet "seq" } "." }
 { $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq" } "." }
 { $examples
@@ -548,7 +548,7 @@ HELP: suffix!
 } ;
 
 HELP: append!
-{ $values { "seq1" sequence } { "seq2" sequence } { "seq1" sequence } }
+{ $values { "seq1" sequence } { "seq2" sequence } }
 { $description "Modifiers " { $snippet "seq1" } " in-place by adding the elements from " { $snippet "seq2" } " to the end and outputs " { $snippet "seq1" } "." }
 { $examples
     { $example "USING: prettyprint sequences ;" "V{ 1 2 3 } { 4 5 6 } append! ." "V{ 1 2 3 4 5 6 }" }
@@ -996,7 +996,7 @@ HELP: count
 HELP: selector
 { $values
      { "quot" "a predicate quotation" }
-     { "quot" quotation } { "accum" vector } }
+     { "selector" quotation } { "accum" vector } }
 { $description "Creates a new vector to accumulate the values which return true for a predicate.  Returns a new quotation which accepts an object to be tested and stored in the collector if the test yields true. The collector is left on the stack for convenience." }
 { $example "! Find all the even numbers:" "USING: prettyprint sequences math kernel ;"
            "10 iota [ even? ] selector [ each ] dip ."
@@ -1202,7 +1202,7 @@ HELP: 2map-reduce
 HELP: 2selector
 { $values
      { "quot" quotation }
-     { "quot" quotation } { "accum1" vector } { "accum2" vector } }
+     { "selector" quotation } { "accum1" vector } { "accum2" vector } }
 { $description "Creates two new vectors to accumultate values based on a predicate. The first vector accumulates values for which the predicate yields true; the second for false." } ;
 
 HELP: 2reverse-each
@@ -1323,8 +1323,7 @@ HELP: sequence-hashcode-step
 
 HELP: short
 { $values
-     { "seq" sequence } { "n" integer }
-     { "seq" sequence } { "n'" integer } }
+     { "seq" sequence } { "n" integer } { "n'" integer } }
 { $description "Returns the input sequence and its length or " { $snippet "n" } ", whichever is less." }
 { $examples { $example "USING: sequences kernel prettyprint ;"
     "\"abcd\" 3 short [ . ] bi@"

core/sequences/sequences.factor

@@ -486,10 +486,10 @@ PRIVATE>
 : push-if ( elt quot accum -- )
     [ keep ] dip rot [ push ] [ 2drop ] if ; inline
 
-: selector-for ( quot exemplar -- quot accum )
+: selector-for ( quot exemplar -- selector accum )
     [ length ] keep new-resizable [ [ push-if ] 2curry ] keep ; inline
 
-: selector ( quot -- quot accum )
+: selector ( quot -- selector accum )
     V{ } selector-for ; inline
 
 : filter-as ( seq quot exemplar -- subseq )
@@ -501,7 +501,7 @@ PRIVATE>
 : push-either ( elt quot accum1 accum2 -- )
     [ keep swap ] 2dip ? push ; inline
 
-: 2selector ( quot -- quot accum1 accum2 )
+: 2selector ( quot -- selector accum1 accum2 )
     V{ } clone V{ } clone [ [ push-either ] 3curry ] 2keep ; inline
 
 : partition ( seq quot -- trueseq falseseq )

extra/game/models/collada/collada-docs.factor

@@ -33,7 +33,7 @@ HELP: y-up { $class-description "Right-handed 3D coordinate system where Y is up
 HELP: z-up { $class-description "Right-handed 3D coordinate system where Z is up." } ;
 
 HELP: >y-up-axis!
-{ $values { "seq" sequence } { "from-axis" rh-up } { "seq" sequence } }
+{ $values { "seq" sequence } { "from-axis" rh-up } }
 { $description "Destructively swizzles the first three elements of the input sequence to a right-handed 3D coordinate system where Y is up and returns the modified sequence." } ;
 
 HELP: source>seq
@@ -53,7 +53,7 @@ HELP: mesh>vertices
 { $description "Convert the mesh tag's vertices element to a pair for further lookup in " { $link collect-sources } ". " } ;
 
 HELP: collect-sources
-{ $values { "sources" hashtable } { "vertices" pair } { "inputs" tag sequence } { "sources" sequence } }
+{ $values { "sources" hashtable } { "vertices" pair } { "inputs" tag sequence } { "seq" sequence } }
 { $description "Look up the sources for these " { $emphasis "input" } " elements and return a sequence of " { $link source } " tuples." } ;
 
 HELP: group-indices

extra/game/models/collada/collada.factor

@@ -94,7 +94,7 @@ M: z-up >y-up-axis!
       ] x*
     ] bi 2array ;
 
-:: collect-sources ( sources vertices inputs -- sources )
+:: collect-sources ( sources vertices inputs -- seq )
     inputs
     [| input |
         input "source" x@ rest vertices first =

extra/game/models/obj/obj-docs.factor

@@ -58,7 +58,7 @@ HELP: face>aos
 { $description "Convert a face line to a sequence of vertex attributes." } ;
 
 HELP: push*
-{ $values { "elt" "an object" } { "seq" sequence } { "seq" sequence } }
+{ $values { "elt" "an object" } { "seq" sequence } }
 { $description "Push the value onto the sequence, keeping the sequence on the stack." } ;
 
 HELP: push-current-model

extra/gpu/shaders/shaders-docs.factor

@@ -172,7 +172,7 @@ HELP: vertex-array
 HELP: vertex-array-buffers
 { $values
     { "vertex-array" vertex-array }
-    { "vertex-buffer" buffer }
+    { "buffers" sequence }
 }
 { $description "Returns a sequence containing all of the " { $link buffer } " objects that make up " { $snippet "vertex-array" } "." } ;
 

extra/math/transforms/fft/fft-docs.factor

@@ -2,6 +2,6 @@ USING: help.markup help.syntax sequences ;
 IN: math.transforms.fft
 
 HELP: fft
-{ $values { "seq" sequence } { "seq" sequence } }
+{ $values { "seq" sequence } { "seq'" sequence } }
 { $description "Fast Fourier transform function." } ;
 

extra/math/transforms/fft/fft.factor

@@ -13,26 +13,26 @@ IN: math.transforms.fft
 : omega ( n -- n' )
     recip -2 pi i* * * exp ;
 
-: twiddle ( seq -- seq )
+: twiddle ( seq -- seq' )
     dup length [ omega ] [ n^v ] bi v* ;
 
 PRIVATE>
 
 DEFER: fft
 
-: two ( seq -- seq )
+: two ( seq -- seq' )
     fft 2 v/n dup append ;
 
 <PRIVATE
 
-: even ( seq -- seq ) 2 group 0 <column> ;
-: odd ( seq -- seq ) 2 group 1 <column> ;
+: even ( seq -- seq' ) 2 group 0 <column> ;
+: odd ( seq -- seq' ) 2 group 1 <column> ;
 
-: (fft) ( seq -- seq )
+: (fft) ( seq -- seq' )
     [ odd two twiddle ] [ even two ] bi v+ ;
 
 PRIVATE>
 
-: fft ( seq -- seq )
+: fft ( seq -- seq' )
     dup length 1 = [ (fft) ] unless ;
 

extra/math/transforms/haar/haar-docs.factor

@@ -2,13 +2,13 @@ USING: help.markup help.syntax sequences ;
 IN: math.transforms.haar
 
 HELP: haar
-{ $values { "seq" sequence } { "seq" sequence } }
+{ $values { "seq" sequence } { "seq'" sequence } }
 { $description "Haar wavelet transform function." }
 { $notes "The sequence length should be a power of two." }
 { $examples { $example "USING: math.transforms.haar prettyprint ;" "{ 7 1 6 6 3 -5 4 2 } haar ." "{ 3 2 -1 -2 3 0 4 1 }" } } ;
 
 HELP: rev-haar
-{ $values { "seq" sequence } { "seq" sequence } }
+{ $values { "seq" sequence } { "seq'" sequence } }
 { $description "Reverse Haar wavelet transform function." }
 { $notes "The sequence length should be a power of two." }
 { $examples { $example "USING: math.transforms.haar prettyprint ;" "{ 3 2 -1 -2 3 0 4 1 } rev-haar ." "{ 7 1 6 6 3 -5 4 2 }" } } ;

extra/math/transforms/haar/haar.factor

@@ -8,7 +8,7 @@ IN: math.transforms.haar
 
 <PRIVATE
 
-: averages ( seq -- seq )
+: averages ( seq -- seq' )
     [ mean ] map ;
 
 : differences ( seq averages -- differences )
@@ -22,9 +22,9 @@ IN: math.transforms.haar
 
 PRIVATE>
 
-: haar ( seq -- seq )
+: haar ( seq -- seq' )
     dup length 1 <= [ haar-step haar prepend ] unless ;
 
-: rev-haar ( seq -- seq )
+: rev-haar ( seq -- seq' )
     dup length 2 > [ halves swap rev-haar prepend ] when rev-haar-step ;
 

extra/memory/piles/piles-docs.factor

@@ -21,7 +21,6 @@ HELP: pile
 HELP: pile-align
 { $values
     { "pile" pile } { "align" "a power of two" }
-    { "pile" pile }
 }
 { $description "Adjusts a " { $link pile } "'s internal state so that the next call to " { $link pile-alloc } " will return a pointer aligned to " { $snippet "align" } " bytes relative to the pile's initial offset." } ;
 

extra/mongodb/driver/driver-docs.factor

@@ -49,7 +49,6 @@ HELP: <update>
 HELP: >upsert
 { $values
   { "mdb-update-msg" "a mdb-update-msg" }
-  { "mdb-update-msg" "mdb-update-msg with the upsert indicator set to t" }
 }
 { $description "Marks a mdb-update-msg as upsert operation"
   "(inserts object identified by the update selector if it doesn't exist in the collection)" } ;
@@ -162,7 +161,6 @@ HELP: hint
 { $values
   { "mdb-query-msg" "a query" }
   { "index-hint" "a hint to an index" }
-  { "mdb-query-msg" "modified query object" }
 }
 { $description "Annotates the query with a hint to an index. "
   "For detailed information see: " { $url "http://www.mongodb.org/display/DOCS/Optimizing+Mongo+Performance#OptimizingMongoPerformance-Hint" } }
@@ -183,7 +181,6 @@ HELP: limit
 { $values
   { "mdb-query-msg" "a query" }
   { "limit#" "number of objects that should be returned at most" }
-  { "mdb-query-msg" "modified query object" }
 }
 { $description "Limits the number of returned objects to limit#" }
 { $examples
@@ -243,7 +240,6 @@ HELP: skip
 { $values
   { "mdb-query-msg" "a query message" }
   { "skip#" "number of objects to skip" }
-  { "mdb-query-msg" "annotated query message" }
 }
 { $description "annotates a query message with a number of objects to skip when returning the results" } ;
 
@@ -251,7 +247,6 @@ HELP: sort
 { $values
   { "mdb-query-msg" "a query message" }
   { "sort-quot" "a quotation with sort specifiers" }
-  { "mdb-query-msg" "annotated query message" }
 }
 { $description "annotates the query message for sort specifiers" } ;
 

extra/spider/spider-docs.factor

@@ -12,7 +12,6 @@ HELP: <spider>
 
 HELP: run-spider
 { $values
-     { "spider" spider }
      { "spider" spider } }
 { $description "Runs a spider until completion. See the " { $subsection "spider-tutorial" } " for a complete description of the tuple slots that affect how thet spider works." } ;