From 5a943b32c4979e18878a9de77e7adba84bccad62 Mon Sep 17 00:00:00 2001 From: John Benediktsson Date: Thu, 20 Oct 2011 19:36:11 -0700 Subject: [PATCH] Remove stack effects from HELP: declarations. --- basis/alien/libraries/libraries-docs.factor | 6 +- basis/bit-arrays/bit-arrays-docs.factor | 2 +- basis/help/syntax/syntax.factor | 11 +-- basis/io/encodings/strict/strict-docs.factor | 2 +- basis/sequences/merged/merged-docs.factor | 12 ++-- basis/tools/profiler/profiler-docs.factor | 2 +- core/alien/alien-docs.factor | 6 +- core/arrays/arrays-docs.factor | 4 +- core/byte-arrays/byte-arrays-docs.factor | 4 +- core/classes/tuple/tuple-docs.factor | 6 +- core/combinators/combinators-docs.factor | 2 +- core/compiler/units/units-docs.factor | 2 +- core/io/streams/c/c-docs.factor | 10 +-- core/kernel/kernel-docs.factor | 58 +++++++-------- core/math/floats/floats-docs.factor | 32 ++++----- core/math/integers/integers-docs.factor | 70 +++++++++---------- core/memory/memory-docs.factor | 8 +-- core/quotations/quotations-docs.factor | 2 +- core/slots/slots-docs.factor | 4 +- core/strings/strings-docs.factor | 2 +- core/system/system-docs.factor | 4 +- core/words/words-docs.factor | 6 +- extra/24-game/24-game-docs.factor | 8 +-- extra/ctags/ctags-docs.factor | 12 ++-- extra/ctags/etags/etags-docs.factor | 8 +-- extra/game/models/collada/collada-docs.factor | 2 +- unmaintained/adsoda/adsoda-docs.factor | 3 +- .../animations/animations-docs.factor | 6 +- .../math/derivatives/derivatives-docs.factor | 2 +- 29 files changed, 143 insertions(+), 153 deletions(-) diff --git a/basis/alien/libraries/libraries-docs.factor b/basis/alien/libraries/libraries-docs.factor index 8676ac8c58..f9828e2835 100644 --- a/basis/alien/libraries/libraries-docs.factor +++ b/basis/alien/libraries/libraries-docs.factor @@ -24,17 +24,17 @@ HELP: library } } ; -HELP: dlopen ( path -- dll ) +HELP: dlopen { $values { "path" "a pathname string" } { "dll" "a DLL handle" } } { $description "Opens a native library and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." } { $errors "Throws an error if the library could not be found, or if loading fails for some other reason." } { $notes "This is the low-level facility used to implement " { $link load-library } ". Use the latter instead." } ; -HELP: dlsym ( name dll -- alien ) +HELP: dlsym { $values { "name" "a C symbol name" } { "dll" "a DLL handle" } { "alien" { $maybe alien } } } { $description "Looks up a symbol in a native library. If " { $snippet "dll" } " is " { $link f } " looks for the symbol in the runtime executable. If the symbol was not found, outputs " { $link f } "." } ; -HELP: dlclose ( dll -- ) +HELP: dlclose { $values { "dll" "a DLL handle" } } { $description "Closes a DLL handle created by " { $link dlopen } ". This word might not be implemented on all platforms." } ; diff --git a/basis/bit-arrays/bit-arrays-docs.factor b/basis/bit-arrays/bit-arrays-docs.factor index 76b636c3f3..df81771ae0 100644 --- a/basis/bit-arrays/bit-arrays-docs.factor +++ b/basis/bit-arrays/bit-arrays-docs.factor @@ -43,7 +43,7 @@ HELP: ?{ HELP: bit-array { $description "The class of fixed-length bit arrays." } ; -HELP: ( n -- bit-array ) +HELP: { $values { "n" "a non-negative integer" } { "bit-array" "a new " { $link bit-array } } } { $description "Creates a new bit array with the given length and all elements initially set to " { $link f } "." } ; diff --git a/basis/help/syntax/syntax.factor b/basis/help/syntax/syntax.factor index 3bf17fdfc3..eac8bc93f8 100644 --- a/basis/help/syntax/syntax.factor +++ b/basis/help/syntax/syntax.factor @@ -5,19 +5,10 @@ effects.parser help help.topics kernel namespaces parser sequences vocabs vocabs.parser words ; IN: help.syntax - - SYNTAX: HELP: scan-word bootstrap-word [ >link save-location ] - [ \ ; parse-until check-effect >array swap set-word-help ] + [ [ \ ; parse-until >array ] dip set-word-help ] bi ; SYNTAX: ARTICLE: diff --git a/basis/io/encodings/strict/strict-docs.factor b/basis/io/encodings/strict/strict-docs.factor index d93c5dd24e..e11bf52467 100644 --- a/basis/io/encodings/strict/strict-docs.factor +++ b/basis/io/encodings/strict/strict-docs.factor @@ -3,6 +3,6 @@ USING: help.syntax help.markup ; IN: io.encodings.strict -HELP: strict ( code -- strict ) +HELP: strict { $values { "code" "an encoding descriptor" } { "strict" "a strict encoding descriptor" } } { $description "Makes an encoding strict, that is, in the presence of a malformed code point, an error is thrown. Note that the existence of a replacement character in a file (U+FFFD) also throws an error." } ; diff --git a/basis/sequences/merged/merged-docs.factor b/basis/sequences/merged/merged-docs.factor index 9b98cd1ed8..0c71135a96 100644 --- a/basis/sequences/merged/merged-docs.factor +++ b/basis/sequences/merged/merged-docs.factor @@ -18,22 +18,22 @@ HELP: merged { $class-description "A virtual sequence which presents a merged view of its underlying elements. New instances are created by calling one of " { $link } ", " { $link <2merged> } ", or " { $link <3merged> } "." } { $see-also merge } ; -HELP: ( seqs -- merged ) +HELP: { $values { "seqs" "a sequence of sequences to merge" } { "merged" "a virtual sequence" } } { $description "Creates an instance of the " { $link merged } " virtual sequence. The length of the created virtual sequences is the minimum length of the input sequences times the number of input sequences." } { $see-also <2merged> <3merged> merge } ; -HELP: <2merged> ( seq1 seq2 -- merged ) +HELP: <2merged> { $values { "seq1" sequence } { "seq2" sequence } { "merged" "a virtual sequence" } } { $description "Creates an instance of the " { $link merged } " virtual sequence which merges the two input sequences." } { $see-also <3merged> 2merge } ; -HELP: <3merged> ( seq1 seq2 seq3 -- merged ) +HELP: <3merged> { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "merged" "a virtual sequence" } } { $description "Creates an instance of the " { $link merged } " virtual sequence which merges the three input sequences." } { $see-also <2merged> 3merge } ; -HELP: merge ( seqs -- seq ) +HELP: merge { $values { "seqs" "a sequence of sequences to merge" } { "seq" "a new sequence" } } { $description "Outputs a new sequence which merges the elements of each sequence in " { $snippet "seqs" } "." } { $examples @@ -42,12 +42,12 @@ HELP: merge ( seqs -- seq ) } { $see-also 2merge 3merge } ; -HELP: 2merge ( seq1 seq2 -- seq ) +HELP: 2merge { $values { "seq1" sequence } { "seq2" sequence } { "seq" "a new sequence" } } { $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of " { $snippet "seq1" } " and " { $snippet "seq2" } } { $see-also merge 3merge <2merged> } ; -HELP: 3merge ( seq1 seq2 seq3 -- seq ) +HELP: 3merge { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "seq" "a new sequence" } } { $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of all three sequences" } { $see-also merge 2merge <3merged> } ; diff --git a/basis/tools/profiler/profiler-docs.factor b/basis/tools/profiler/profiler-docs.factor index 66ae5d7bd3..ee1d884073 100644 --- a/basis/tools/profiler/profiler-docs.factor +++ b/basis/tools/profiler/profiler-docs.factor @@ -61,7 +61,7 @@ HELP: vocabs-profile. HELP: method-profile. { $description "Print a table of cumilative call counts for each method. Methods which were not called are supressed from the output." } ; -HELP: profiling ( ? -- ) +HELP: profiling { $values { "?" "a boolean" } } { $description "Internal primitive to switch on call counting. This word should not be used; instead use " { $link profile } "." } ; diff --git a/core/alien/alien-docs.factor b/core/alien/alien-docs.factor index a4c88a49b0..edfdb15070 100644 --- a/core/alien/alien-docs.factor +++ b/core/alien/alien-docs.factor @@ -41,7 +41,7 @@ HELP: alien HELP: dll { $class-description "The class of native library handles. See " { $link "syntax-aliens" } " for syntax and " { $link "dll.private" } " for general information." } ; -HELP: dll-valid? ( dll -- ? ) +HELP: dll-valid? { $values { "dll" dll } { "?" "a boolean" } } { $description "Returns true if the library exists and is loaded." } ; @@ -53,7 +53,7 @@ HELP: { $values { "alien" c-ptr } } { $description "Constructs an invalid alien pointer that has expired." } ; -HELP: ( displacement c-ptr -- alien ) +HELP: { $values { "displacement" "an integer" } { "c-ptr" c-ptr } { "alien" "a new alien" } } { $description "Creates a new alien address object, wrapping a raw memory address. The alien points to a location in memory which is offset by " { $snippet "displacement" } " from the address of " { $snippet "c-ptr" } "." } { $notes "Passing a value of " { $link f } " for " { $snippet "c-ptr" } " creates an alien with an absolute address; this is how " { $link } " is implemented." @@ -62,7 +62,7 @@ $nl { alien-address } related-words -HELP: alien-address ( c-ptr -- addr ) +HELP: alien-address { $values { "c-ptr" c-ptr } { "addr" "a non-negative integer" } } { $description "Outputs the address of an alien." } { $notes "Taking the address of a " { $link byte-array } " is explicitly prohibited since byte arrays can be moved by the garbage collector between the time the address is taken, and when it is accessed. If you need to pass pointers to C functions which will persist across alien calls, you must allocate unmanaged memory instead. See " { $link "malloc" } "." } ; diff --git a/core/arrays/arrays-docs.factor b/core/arrays/arrays-docs.factor index 1220112bd7..5cdfcd3a80 100644 --- a/core/arrays/arrays-docs.factor +++ b/core/arrays/arrays-docs.factor @@ -45,7 +45,7 @@ ABOUT: "arrays" HELP: array { $description "The class of fixed-length arrays. See " { $link "syntax-arrays" } " for syntax and " { $link "arrays" } " for general information." } ; -HELP: ( n elt -- array ) +HELP: { $values { "n" "a non-negative integer" } { "elt" "an initial element" } { "array" "a new array" } } { $description "Creates a new array with the given length and all elements initially set to " { $snippet "elt" } "." } ; @@ -71,7 +71,7 @@ HELP: 4array { $values { "w" object } { "x" object } { "y" object } { "z" object } { "array" array } } { $description "Create a new array with four elements, with " { $snippet "w" } " appearing first." } ; -HELP: resize-array ( n array -- new-array ) +HELP: resize-array { $values { "n" "a non-negative integer" } { "array" array } { "new-array" array } } { $description "Resizes the array to have a length of " { $snippet "n" } " elements. When making the array shorter, this word may either create a new array or modify the existing array in place. When making the array longer, this word always allocates a new array, filling remaining space with " { $link f } "." } { $side-effects "array" } ; diff --git a/core/byte-arrays/byte-arrays-docs.factor b/core/byte-arrays/byte-arrays-docs.factor index f804802fa7..943d2822e5 100644 --- a/core/byte-arrays/byte-arrays-docs.factor +++ b/core/byte-arrays/byte-arrays-docs.factor @@ -30,7 +30,7 @@ ABOUT: "byte-arrays" HELP: byte-array { $description "The class of byte arrays. See " { $link "syntax-byte-arrays" } " for syntax and " { $link "byte-arrays" } " for general information." } ; -HELP: ( n -- byte-array ) +HELP: { $values { "n" "a non-negative integer" } { "byte-array" "a new byte array" } } { $description "Creates a new byte array holding " { $snippet "n" } " bytes." } ; @@ -70,7 +70,7 @@ HELP: 4byte-array { 1byte-array 2byte-array 3byte-array 4byte-array } related-words -HELP: resize-byte-array ( n byte-array -- new-byte-array ) +HELP: resize-byte-array { $values { "n" "a non-negative integer" } { "byte-array" byte-array } { "new-byte-array" byte-array } } { $description "Resizes the byte array to have a length of " { $snippet "n" } " elements. When making the byte array shorter, this word may either create a new byte array or modify the existing byte array in place. When making the byte array longer, this word always allocates a new byte array, filling remaining space with zeroes." } { $side-effects "byte-array" } ; diff --git a/core/classes/tuple/tuple-docs.factor b/core/classes/tuple/tuple-docs.factor index 07df34cdad..7fd0cb0850 100644 --- a/core/classes/tuple/tuple-docs.factor +++ b/core/classes/tuple/tuple-docs.factor @@ -415,15 +415,15 @@ $nl } } ; -HELP: tuple>array ( tuple -- array ) +HELP: tuple>array { $values { "tuple" tuple } { "array" array } } { $description "Outputs an array having the tuple's slots as elements. The first element is the tuple class word and remainder are declared slots." } ; -HELP: ( layout -- tuple ) +HELP: { $values { "layout" "a tuple layout array" } { "tuple" tuple } } { $description "Low-level tuple constructor. User code should never call this directly, and instead use " { $link new } "." } ; -HELP: ( slots... layout -- tuple ) +HELP: { $values { "slots..." "values" } { "layout" "a tuple layout array" } { "tuple" tuple } } { $description "Low-level tuple constructor. User code should never call this directly, and instead use " { $link boa } "." } ; diff --git a/core/combinators/combinators-docs.factor b/core/combinators/combinators-docs.factor index e0b9c09cb2..8caa39c652 100644 --- a/core/combinators/combinators-docs.factor +++ b/core/combinators/combinators-docs.factor @@ -398,7 +398,7 @@ HELP: distribute-buckets { $description "Sorts the entries of " { $snippet "assoc" } " into buckets, using the quotation to yield a set of keys for each entry. The hashcode of each key is computed, and the entry is placed in all corresponding buckets. Each bucket is initially cloned from " { $snippet "initial" } "; this should either be an empty vector or a one-element vector containing a pair." } { $notes "This word is used in the implementation of " { $link hash-case-quot } " and " { $link standard-combination } "." } ; -HELP: dispatch ( n array -- ) +HELP: dispatch { $values { "n" "a fixnum" } { "array" "an array of quotations" } } { $description "Calls the " { $snippet "n" } "th quotation in the array." } { $warning "This word is in the " { $vocab-link "kernel.private" } " vocabulary because it is an implementation detail used by the generic word system to accelerate method dispatch. It does not perform type or bounds checks, and user code should not need to call it directly." } ; diff --git a/core/compiler/units/units-docs.factor b/core/compiler/units/units-docs.factor index ea261d7c7e..4696132579 100644 --- a/core/compiler/units/units-docs.factor +++ b/core/compiler/units/units-docs.factor @@ -78,7 +78,7 @@ HELP: no-compilation-unit { $description "Throws a " { $link no-compilation-unit } " error." } { $error-description "Thrown when an attempt is made to define a word outside of a " { $link with-compilation-unit } " combinator." } ; -HELP: modify-code-heap ( alist update-existing? reset-pics? -- ) +HELP: modify-code-heap { $values { "alist" "an association list with words as keys" } { "update-existing?" "a boolean" } { "reset-pics?" "a boolean" } } { $description "Lowest-level primitive for defining words. Associates words with code blocks in the code heap." $nl diff --git a/core/io/streams/c/c-docs.factor b/core/io/streams/c/c-docs.factor index 63fabc1f90..531cc9678e 100644 --- a/core/io/streams/c/c-docs.factor +++ b/core/io/streams/c/c-docs.factor @@ -48,26 +48,26 @@ HELP: fwrite { $description "Writes some bytes to a C FILE* handle." } { $errors "Throws an error if the output operation failed." } ; -HELP: fflush ( alien -- ) +HELP: fflush { $values { "alien" "a C FILE* handle" } } { $description "Forces pending output on a C FILE* handle to complete." } { $errors "Throws an error if the output operation failed." } ; -HELP: fclose ( alien -- ) +HELP: fclose { $values { "alien" "a C FILE* handle" } } { $description "Closes a C FILE* handle." } ; -HELP: fgetc ( alien -- byte/f ) +HELP: fgetc { $values { "alien" "a C FILE* handle" } { "byte/f" "an integer from 0 to 255 or " { $link f } } } { $description "Reads a single byte from a C FILE* handle, and outputs " { $link f } " on end of file." } { $errors "Throws an error if the input operation failed." } ; -HELP: fputc ( byte alien -- ) +HELP: fputc { $values { "byte" "an integer from 0 to 255" } { "alien" "a C FILE* handle" } } { $description "Writes a single byte to a C FILE* handle." } { $errors "Throws an error if the output operation failed." } ; -HELP: fread-unsafe ( n buf alien -- str/f ) +HELP: fread-unsafe { $values { "n" "a positive integer" } { "buf" c-ptr } { "alien" "a C FILE* handle" } { "count" integer } } { $description "Reads " { $snippet "n" } " bytes from a C FILE* handle into the memory referenced by " { $snippet "buf" } ", and outputs the number of characters read. Zero is output on end of file." } { $warning "This word does not check whether " { $snippet "buf" } " is large enough to accommodate the requested number of bytes. Memory corruption will occur if this is not the case." } diff --git a/core/kernel/kernel-docs.factor b/core/kernel/kernel-docs.factor index 892850ad4c..161b76c6d4 100644 --- a/core/kernel/kernel-docs.factor +++ b/core/kernel/kernel-docs.factor @@ -4,49 +4,49 @@ vectors combinators quotations strings words assocs arrays math.order ; IN: kernel -HELP: eq? ( obj1 obj2 -- ? ) +HELP: eq? { $values { "obj1" object } { "obj2" object } { "?" "a boolean" } } { $description "Tests if two references point at the same object." } ; -HELP: drop ( x -- ) $shuffle ; -HELP: 2drop ( x y -- ) $shuffle ; -HELP: 3drop ( x y z -- ) $shuffle ; -HELP: dup ( x -- x x ) $shuffle ; -HELP: 2dup ( x y -- x y x y ) $shuffle ; -HELP: 3dup ( x y z -- x y z x y z ) $shuffle ; -HELP: nip ( x y -- y ) $shuffle ; -HELP: 2nip ( x y z -- z ) $shuffle ; -HELP: over ( x y -- x y x ) $shuffle ; -HELP: 2over $shuffle ; -HELP: pick ( x y z -- x y z x ) $shuffle ; -HELP: swap ( x y -- y x ) $shuffle ; - -HELP: rot ( x y z -- y z x ) $complex-shuffle ; -HELP: -rot ( x y z -- z x y ) $complex-shuffle ; -HELP: dupd ( x y -- x x y ) $complex-shuffle ; -HELP: swapd ( x y z -- y x z ) $complex-shuffle ; - -HELP: datastack ( -- array ) +HELP: drop $shuffle ; +HELP: 2drop $shuffle ; +HELP: 3drop $shuffle ; +HELP: dup $shuffle ; +HELP: 2dup $shuffle ; +HELP: 3dup $shuffle ; +HELP: nip $shuffle ; +HELP: 2nip $shuffle ; +HELP: over $shuffle ; +HELP: 2over $shuffle ; +HELP: pick $shuffle ; +HELP: swap $shuffle ; + +HELP: rot $complex-shuffle ; +HELP: -rot $complex-shuffle ; +HELP: dupd $complex-shuffle ; +HELP: swapd $complex-shuffle ; + +HELP: datastack { $values { "array" array } } { $description "Outputs an array containing a copy of the data stack contents right before the call to this word, with the top of the stack at the end of the array." } ; -HELP: set-datastack ( array -- ) +HELP: set-datastack { $values { "array" array } } { $description "Replaces the data stack contents with a copy of an array. The end of the array becomes the top of the stack." } ; -HELP: retainstack ( -- array ) +HELP: retainstack { $values { "array" array } } { $description "Outputs an array containing a copy of the retain stack contents right before the call to this word, with the top of the stack at the end of the array." } ; -HELP: set-retainstack ( array -- ) +HELP: set-retainstack { $values { "array" array } } { $description "Replaces the retain stack contents with a copy of an array. The end of the array becomes the top of the stack." } ; -HELP: callstack ( -- callstack ) +HELP: callstack { $values { "callstack" callstack } } { $description "Outputs a copy of the call stack contents, with the top of the stack at the end of the vector. The stack frame of the caller word is " { $emphasis "not" } " included." } ; -HELP: set-callstack ( callstack -- * ) +HELP: set-callstack { $values { "callstack" callstack } } { $description "Replaces the call stack contents. Control flow is transferred immediately to the innermost frame of the new call stack." } ; @@ -688,7 +688,7 @@ HELP: die { $url "http://www.jargon.net/jargonfile/f/feppedout.html" } } ; -HELP: (clone) ( obj -- newobj ) +HELP: (clone) { $values { "obj" object } { "newobj" "a shallow copy" } } { $description "Outputs a byte-by-byte copy of the given object. User code should call " { $link clone } " instead." } ; @@ -703,15 +703,15 @@ HELP: declare { $code "{ float } declare 2 + 10 *" } } ; -HELP: tag ( object -- n ) +HELP: tag { $values { "object" object } { "n" "a tag number" } } { $description "Outputs an object's tag number, between zero and one less than " { $link num-types } ". This is implementation detail and user code should call " { $link class } " instead." } ; -HELP: special-object ( n -- obj ) +HELP: special-object { $values { "n" "a non-negative integer" } { "obj" object } } { $description "Reads an object from the Factor VM's special object table. User code never has to read the special object table directly; instead, use one of the callers of this word." } ; -HELP: set-special-object ( obj n -- ) +HELP: set-special-object { $values { "obj" object } { "n" "a non-negative integer" } } { $description "Writes an object to the Factor VM's special object table. User code never has to write to the special object table directly; instead, use one of the callers of this word." } ; diff --git a/core/math/floats/floats-docs.factor b/core/math/floats/floats-docs.factor index 7f0667bf74..2eedd0f194 100644 --- a/core/math/floats/floats-docs.factor +++ b/core/math/floats/floats-docs.factor @@ -8,81 +8,81 @@ HELP: >float { $values { "x" real } { "y" float } } { $description "Converts a real to a float. This is the identity on floats, and performs a floating point division on rationals." } ; -HELP: bits>double ( n -- x ) +HELP: bits>double { $values { "n" "a 64-bit integer representing an IEEE 754 double-precision float" } { "x" float } } { $description "Creates a " { $link float } " object from a 64-bit binary representation. This word is usually used to reconstruct floats read from streams." } ; { bits>double bits>float double>bits float>bits } related-words -HELP: bits>float ( n -- x ) +HELP: bits>float { $values { "n" "a 32-bit integer representing an IEEE 754 single-precision float" } { "x" float } } { $description "Creates a " { $link float } " object from a 32-bit binary representation. This word is usually used to reconstruct floats read from streams." } ; -HELP: double>bits ( x -- n ) +HELP: double>bits { $values { "x" float } { "n" "a 64-bit integer representing an IEEE 754 double-precision float" } } { $description "Creates a 64-bit binary representation of a " { $link float } " object. This can be used in the process of writing a float to a stream." } ; -HELP: float>bits ( x -- n ) +HELP: float>bits { $values { "x" float } { "n" "a 32-bit integer representing an IEEE 754 single-precision float" } } { $description "Creates a 32-bit binary representation of a " { $link float } " object. This can be used in the process of writing a float to a stream." } ; ! Unsafe primitives -HELP: float+ ( x y -- z ) +HELP: float+ { $values { "x" float } { "y" float } { "z" float } } { $description "Primitive version of " { $link + } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ; -HELP: float- ( x y -- z ) +HELP: float- { $values { "x" float } { "y" float } { "z" float } } { $description "Primitive version of " { $link - } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ; -HELP: float* ( x y -- z ) +HELP: float* { $values { "x" float } { "y" float } { "z" float } } { $description "Primitive version of " { $link * } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ; -HELP: float/f ( x y -- z ) +HELP: float/f { $values { "x" float } { "y" float } { "z" float } } { $description "Primitive version of " { $link /f } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /f } " instead." } ; -HELP: float< ( x y -- ? ) +HELP: float< { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link < } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ; -HELP: float<= ( x y -- ? ) +HELP: float<= { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link <= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ; -HELP: float> ( x y -- ? ) +HELP: float> { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link > } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ; -HELP: float>= ( x y -- ? ) +HELP: float>= { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link u>= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u>= } " instead." } ; -HELP: float-u< ( x y -- ? ) +HELP: float-u< { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link u< } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u< } " instead." } ; -HELP: float-u<= ( x y -- ? ) +HELP: float-u<= { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link u<= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u<= } " instead." } ; -HELP: float-u> ( x y -- ? ) +HELP: float-u> { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link u> } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u> } " instead." } ; -HELP: float-u>= ( x y -- ? ) +HELP: float-u>= { $values { "x" float } { "y" float } { "?" "a boolean" } } { $description "Primitive version of " { $link u>= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u>= } " instead." } ; diff --git a/core/math/integers/integers-docs.factor b/core/math/integers/integers-docs.factor index e25bbf13e2..6f1dbece37 100644 --- a/core/math/integers/integers-docs.factor +++ b/core/math/integers/integers-docs.factor @@ -52,177 +52,177 @@ HELP: odd? { $description "Tests if an integer is odd." } ; ! Unsafe primitives -HELP: fixnum+ ( x y -- z ) +HELP: fixnum+ { $values { "x" fixnum } { "y" fixnum } { "z" integer } } { $description "Primitive version of " { $link + } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ; -HELP: fixnum- ( x y -- z ) +HELP: fixnum- { $values { "x" fixnum } { "y" fixnum } { "z" integer } } { $description "Primitive version of " { $link - } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ; -HELP: fixnum* ( x y -- z ) +HELP: fixnum* { $values { "x" fixnum } { "y" fixnum } { "z" integer } } { $description "Primitive version of " { $link * } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ; -HELP: fixnum/i ( x y -- z ) +HELP: fixnum/i { $values { "x" fixnum } { "y" fixnum } { "z" integer } } { $description "Primitive version of " { $link /i } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ; -HELP: fixnum-mod ( x y -- z ) +HELP: fixnum-mod { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link mod } ". The result always fits in a fixnum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ; -HELP: fixnum/mod ( x y -- z w ) +HELP: fixnum/mod { $values { "x" fixnum } { "y" fixnum } { "z" integer } { "w" fixnum } } { $description "Primitive version of " { $link /mod } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ; -HELP: fixnum< ( x y -- ? ) +HELP: fixnum< { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } } { $description "Primitive version of " { $link < } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ; -HELP: fixnum<= ( x y -- z ) +HELP: fixnum<= { $values { "x" fixnum } { "y" fixnum } { "z" integer } } { $description "Primitive version of " { $link <= } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ; -HELP: fixnum> ( x y -- ? ) +HELP: fixnum> { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } } { $description "Primitive version of " { $link > } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ; -HELP: fixnum>= ( x y -- ? ) +HELP: fixnum>= { $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } } { $description "Primitive version of " { $link >= } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ; -HELP: fixnum-bitand ( x y -- z ) +HELP: fixnum-bitand { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link bitand } ". The result always fits in a fixnum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ; -HELP: fixnum-bitor ( x y -- z ) +HELP: fixnum-bitor { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link bitor } ". The result always fits in a fixnum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ; -HELP: fixnum-bitxor ( x y -- z ) +HELP: fixnum-bitxor { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link bitxor } ". The result always fits in a fixnum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ; -HELP: fixnum-bitnot ( x -- y ) +HELP: fixnum-bitnot { $values { "x" fixnum } { "y" fixnum } } { $description "Primitive version of " { $link bitnot } ". The result always fits in a fixnum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ; -HELP: fixnum-shift ( x y -- z ) +HELP: fixnum-shift { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link shift } ". The result may overflow to a bignum." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ; -HELP: fixnum-shift-fast ( x y -- z ) +HELP: fixnum-shift-fast { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link shift } ". Unlike " { $link fixnum-shift } ", does not perform an overflow check, so the result may be incorrect." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ; -HELP: fixnum+fast ( x y -- z ) +HELP: fixnum+fast { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link + } ". Unlike " { $link fixnum+ } ", does not perform an overflow check, so the result may be incorrect." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ; -HELP: fixnum-fast ( x y -- z ) +HELP: fixnum-fast { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link - } ". Unlike " { $link fixnum- } ", does not perform an overflow check, so the result may be incorrect." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ; -HELP: fixnum*fast ( x y -- z ) +HELP: fixnum*fast { $values { "x" fixnum } { "y" fixnum } { "z" fixnum } } { $description "Primitive version of " { $link * } ". Unlike " { $link fixnum* } ", does not perform an overflow check, so the result may be incorrect." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ; -HELP: bignum+ ( x y -- z ) +HELP: bignum+ { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link + } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ; -HELP: bignum- ( x y -- z ) +HELP: bignum- { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link - } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ; -HELP: bignum* ( x y -- z ) +HELP: bignum* { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link * } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ; -HELP: bignum/i ( x y -- z ) +HELP: bignum/i { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link /i } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ; -HELP: bignum-mod ( x y -- z ) +HELP: bignum-mod { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link mod } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ; -HELP: bignum/mod ( x y -- z w ) +HELP: bignum/mod { $values { "x" bignum } { "y" bignum } { "z" bignum } { "w" bignum } } { $description "Primitive version of " { $link /mod } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ; -HELP: bignum< ( x y -- ? ) +HELP: bignum< { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } } { $description "Primitive version of " { $link < } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ; -HELP: bignum<= ( x y -- ? ) +HELP: bignum<= { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } } { $description "Primitive version of " { $link <= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ; -HELP: bignum> ( x y -- ? ) +HELP: bignum> { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } } { $description "Primitive version of " { $link > } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ; -HELP: bignum>= ( x y -- ? ) +HELP: bignum>= { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } } { $description "Primitive version of " { $link >= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ; -HELP: bignum= ( x y -- ? ) +HELP: bignum= { $values { "x" bignum } { "y" bignum } { "?" "a boolean" } } { $description "Primitive version of " { $link number= } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link number= } " instead." } ; -HELP: bignum-bitand ( x y -- z ) +HELP: bignum-bitand { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link bitand } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ; -HELP: bignum-bitor ( x y -- z ) +HELP: bignum-bitor { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link bitor } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ; -HELP: bignum-bitxor ( x y -- z ) +HELP: bignum-bitxor { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link bitxor } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ; -HELP: bignum-bitnot ( x -- y ) +HELP: bignum-bitnot { $values { "x" bignum } { "y" bignum } } { $description "Primitive version of " { $link bitnot } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ; -HELP: bignum-shift ( x y -- z ) +HELP: bignum-shift { $values { "x" bignum } { "y" bignum } { "z" bignum } } { $description "Primitive version of " { $link shift } "." } { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ; diff --git a/core/memory/memory-docs.factor b/core/memory/memory-docs.factor index 29ac20a14c..afc9758ba0 100644 --- a/core/memory/memory-docs.factor +++ b/core/memory/memory-docs.factor @@ -6,18 +6,18 @@ HELP: instances { $values { "quot" { $quotation "( obj -- ? )" } } { "seq" "a fresh sequence" } } { $description "Outputs a sequence of all objects in the heap which satisfy the quotation." } ; -HELP: gc ( -- ) +HELP: gc { $description "Performs a full garbage collection." } ; -HELP: size ( obj -- n ) +HELP: size { $values { "obj" "an object" } { "n" "a size in bytes" } } { $description "Outputs the size of the object in memory, in bytes. Tagged immediate objects such as fixnums and " { $link f } " will yield a size of 0." } ; -HELP: save-image ( path -- ) +HELP: save-image { $values { "path" "a pathname string" } } { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists." } ; -HELP: save-image-and-exit ( path -- ) +HELP: save-image-and-exit { $values { "path" "a pathname string" } } { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists. This word compacts the code heap and immediately exits Factor, since the Factor VM cannot continue executing after compiled code blocks have been moved around." } ; diff --git a/core/quotations/quotations-docs.factor b/core/quotations/quotations-docs.factor index 6f742007bf..10f0ac10dc 100644 --- a/core/quotations/quotations-docs.factor +++ b/core/quotations/quotations-docs.factor @@ -64,7 +64,7 @@ HELP: 1quotation HELP: wrapper { $description "The class of wrappers. Wrappers are created by calling " { $link literalize } ". See " { $link "syntax-words" } " for syntax." } ; -HELP: ( obj -- wrapper ) +HELP: { $values { "obj" object } { "wrapper" wrapper } } { $description "Creates an object which pushes " { $snippet "obj" } " on the stack when evaluated. User code should call " { $link literalize } " instead, since it avoids wrapping self-evaluating objects (which is redundant)." } ; diff --git a/core/slots/slots-docs.factor b/core/slots/slots-docs.factor index 1334954b6b..24796768c1 100644 --- a/core/slots/slots-docs.factor +++ b/core/slots/slots-docs.factor @@ -162,12 +162,12 @@ HELP: define-accessors { $description "Defines slot methods." } $low-level-note ; -HELP: slot ( obj m -- value ) +HELP: slot { $values { "obj" object } { "m" "a non-negative fixnum" } { "value" object } } { $description "Reads the object stored at the " { $snippet "n" } "th slot of " { $snippet "obj" } "." } { $warning "This word is in the " { $vocab-link "slots.private" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ; -HELP: set-slot ( value obj n -- ) +HELP: set-slot { $values { "value" object } { "obj" object } { "n" "a non-negative fixnum" } } { $description "Writes " { $snippet "value" } " to the " { $snippet "n" } "th slot of " { $snippet "obj" } "." } { $warning "This word is in the " { $vocab-link "slots.private" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ; diff --git a/core/strings/strings-docs.factor b/core/strings/strings-docs.factor index d53282114b..b176b8868e 100644 --- a/core/strings/strings-docs.factor +++ b/core/strings/strings-docs.factor @@ -53,7 +53,7 @@ HELP: >string { $notes "This operation is only appropriate if the underlying sequence holds Unicode code points, which is rare unless it is a " { $link slice } " of another string. To convert a sequence of bytes to a string, use the words documented in " { $link "io.encodings.string" } "." } { $errors "Throws an error if the sequence contains elements other than integers." } ; -HELP: resize-string ( n str -- newstr ) +HELP: resize-string { $values { "n" "a non-negative integer" } { "str" string } { "newstr" string } } { $description "Resizes the string to have a length of " { $snippet "n" } " elements. When making the string shorter, this word may either create a new string or modify the existing string in place. When making the string longer, this word always allocates a new string, filling remaining space with zeroes." } { $side-effects "str" } ; diff --git a/core/system/system-docs.factor b/core/system/system-docs.factor index ee2fbe4cf3..9829eeca9b 100644 --- a/core/system/system-docs.factor +++ b/core/system/system-docs.factor @@ -69,11 +69,11 @@ HELP: embedded? { $values { "?" "a boolean" } } { $description "Tests if this Factor instance is embedded in another application." } ; -HELP: exit ( n -- * ) +HELP: exit { $values { "n" "an integer exit code" } } { $description "Exits the Factor process." } ; -HELP: nano-count ( -- ns ) +HELP: nano-count { $values { "ns" integer } } { $description "Outputs a monotonically increasing count of nanoseconds elapsed since an arbitrary starting time. The difference of two calls to this word allows timing. This word is unaffected by system clock changes." } { $notes "This is a low-level word. The " { $vocab-link "tools.time" } " vocabulary defines words to time code execution time." } ; diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index d4a60a5350..0cf0076d4f 100644 --- a/core/words/words-docs.factor +++ b/core/words/words-docs.factor @@ -218,7 +218,7 @@ HELP: remove-word-prop { $description "Removes a word property, so future lookups will output " { $link f } " until it is set again. Word property names are conventionally strings." } { $side-effects "word" } ; -HELP: word-code ( word -- start end ) +HELP: word-code { $values { "word" word } { "start" "the word's start address" } { "end" "the word's end address" } } { $description "Outputs the memory range containing the word's machine code." } ; @@ -245,12 +245,12 @@ HELP: reset-generic $low-level-note { $side-effects "word" } ; -HELP: ( name vocab -- word ) +HELP: { $values { "name" string } { "vocab" string } { "word" word } } { $description "Allocates a word with the specified name and vocabulary. User code should call " { $link } " to create uninterned words and " { $link create } " to create interned words, instead of calling this constructor directly." } { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ; -HELP: ( name -- word ) +HELP: { $values { "name" string } { "word" word } } { $description "Creates an uninterned word with the specified name, that is not equal to any other word in the system." } { $notes "Unlike " { $link create } ", this word does not have to be called from inside " { $link with-compilation-unit } "." } ; diff --git a/extra/24-game/24-game-docs.factor b/extra/24-game/24-game-docs.factor index a23a0055db..248f6b7d4e 100644 --- a/extra/24-game/24-game-docs.factor +++ b/extra/24-game/24-game-docs.factor @@ -1,7 +1,7 @@ USING: help.markup help.syntax math kernel ; IN: 24-game -HELP: play-game ( -- ) +HELP: play-game { $description "Starts the game!" } { $examples { $unchecked-example @@ -23,7 +23,7 @@ HELP: play-game ( -- ) } } ; -HELP: 24-able ( -- vector ) +HELP: 24-able { $values { "vector" "vector of 4 integers" } } { $description "Produces a vector with 4 integers. With the following condition: " @@ -42,7 +42,7 @@ HELP: 24-able ( -- vector ) { $notes { $link 24-able? } " is used in " { $link 24-able } "." } } ; -HELP: 24-able? ( quad -- t/f ) +HELP: 24-able? { $values { "quad" "vector of 4 integers" } { "t/f" "a boolean" } @@ -52,7 +52,7 @@ HELP: 24-able? ( quad -- t/f ) "with this sequence." } ; -HELP: build-quad ( -- array ) +HELP: build-quad { $values { "array" "an array of 4 numbers" } } diff --git a/extra/ctags/ctags-docs.factor b/extra/ctags/ctags-docs.factor index 5b7f17f278..5edaf237e8 100644 --- a/extra/ctags/ctags-docs.factor +++ b/extra/ctags/ctags-docs.factor @@ -13,7 +13,7 @@ ARTICLE: "ctags" "Ctags file" ctag-lineno } ; -HELP: ctags ( path -- ) +HELP: ctags { $values { "path" "a pathname string" } } { $description "Generates a index file in ctags format and stores in " { $snippet "path" } "." } { $examples @@ -24,7 +24,7 @@ HELP: ctags ( path -- ) } } ; -HELP: ctags-write ( seq path -- ) +HELP: ctags-write { $values { "seq" sequence } { "path" "a pathname string" } } { $description "Stores a " { $snippet "alist" } " in " { $snippet "path" } ". " { $snippet "alist" } " must be an association list with ctags format: key must be a valid word and value a sequence whose first element is a resource name and second element is a line number" } @@ -50,7 +50,7 @@ HELP: ctag-strings } } ; -HELP: ctag ( seq -- str ) +HELP: ctag { $values { "seq" sequence } { "str" string } } { $description "Outputs a string " { $snippet "str" } " in ctag format for sequence with two elements, first one must be a valid word and second one a sequence whose first element is a resource name and second element is a line number" } @@ -62,7 +62,7 @@ HELP: ctag ( seq -- str ) } } ; -HELP: ctag-lineno ( ctag -- n ) +HELP: ctag-lineno { $values { "ctag" sequence } { "n" integer } } { $description "Provides de line number " { $snippet "n" } " from a sequence in ctag format " } @@ -74,7 +74,7 @@ HELP: ctag-lineno ( ctag -- n ) } } ; -HELP: ctag-path ( ctag -- path ) +HELP: ctag-path { $values { "ctag" sequence } { "path" string } } { $description "Provides a path string " { $snippet "path" } " from a sequence in ctag format" } @@ -86,7 +86,7 @@ HELP: ctag-path ( ctag -- path ) } } ; -HELP: ctag-word ( ctag -- word ) +HELP: ctag-word { $values { "ctag" sequence } { "word" word } } { $description "Provides the " { $snippet "word" } " from a sequence in ctag format " } diff --git a/extra/ctags/etags/etags-docs.factor b/extra/ctags/etags/etags-docs.factor index 28ca7ff165..a21ec232cc 100644 --- a/extra/ctags/etags/etags-docs.factor +++ b/extra/ctags/etags/etags-docs.factor @@ -10,7 +10,7 @@ ARTICLE: "etags" "Etags file" etag-header } -HELP: etags ( path -- ) +HELP: etags { $values { "path" string } } { $description "Generates a index file in etags format and stores in " { $snippet "path" } "." } { $examples @@ -21,7 +21,7 @@ HELP: etags ( path -- ) } } ; -HELP: etags-write ( alist path -- ) +HELP: etags-write { $values { "alist" sequence } { "path" string } } { $description "Stores a " { $snippet "alist" } " in " { $snippet "path" } ". " { $snippet "alist" } " must be an association list with etags format: its key must be a resource path and its value a vector, containing pairs of words and lines" } @@ -33,9 +33,9 @@ HELP: etags-write ( alist path -- ) } } ; -HELP: etag-strings ( alist -- seq ) +HELP: etag-strings { $values { "alist" sequence } { "seq" sequence } } { $description "Converts an " { $snippet "alist" } " with etag format (a path as key and a vector containing word/line pairs) in a " { $snippet "seq" } " of strings." } ; -ABOUT: "etags" ; \ No newline at end of file +ABOUT: "etags" ; diff --git a/extra/game/models/collada/collada-docs.factor b/extra/game/models/collada/collada-docs.factor index ac286cae24..acd180a906 100644 --- a/extra/game/models/collada/collada-docs.factor +++ b/extra/game/models/collada/collada-docs.factor @@ -20,7 +20,7 @@ HELP: up-axis HELP: unit-ratio { $description "Scaling ratio for the coordinates of the tags being read." } ; -HELP: string>numbers ( string -- number-seq ) +HELP: string>numbers { $values { "string" string } { "number-seq" sequence } } { $description "Splits a string on whitespace and converts the elements to a number sequence." } ; diff --git a/unmaintained/adsoda/adsoda-docs.factor b/unmaintained/adsoda/adsoda-docs.factor index 9536826c92..029af8d872 100644 --- a/unmaintained/adsoda/adsoda-docs.factor +++ b/unmaintained/adsoda/adsoda-docs.factor @@ -202,7 +202,6 @@ HELP: space-ensure-solids HELP: space-transform -" ( space m -- space )" { $values { "space" "a space" } { "m" "a matrix" } } { $description "Transform a space using a matrix" } ; @@ -210,7 +209,7 @@ HELP: space-translate { $values { "space" "a space" } { "v" "a vector" } } { $description "Translate a space following a vector" } ; -HELP: describe-space " ( space -- )" +HELP: describe-space { $values { "space" "a space" } } { $description "return a description of space" } ; diff --git a/unmaintained/animations/animations-docs.factor b/unmaintained/animations/animations-docs.factor index 3e426a2c64..20092aa40d 100644 --- a/unmaintained/animations/animations-docs.factor +++ b/unmaintained/animations/animations-docs.factor @@ -1,7 +1,7 @@ USING: help.markup help.syntax ; IN: animations -HELP: animate ( quot duration -- ) +HELP: animate { $values { "quot" "a quot which uses " { $link progress } } @@ -23,7 +23,7 @@ HELP: animate ( quot duration -- ) { $notes "The amount of time elapsed between these iterations will very." } } ; -HELP: reset-progress ( -- ) +HELP: reset-progress { $description "Initiates the timer. Call this before using " "a loop which makes use of " { $link progress } "." @@ -64,4 +64,4 @@ ARTICLE: "animations" "Animations" "used when one's quote runs for a specific number of iterations, instead " "of a length of time. If the animation is like most, and is expected to " "run for a specific length of time, " { $link animate } " should be used." ; -ABOUT: "animations" \ No newline at end of file +ABOUT: "animations" diff --git a/unmaintained/math/derivatives/derivatives-docs.factor b/unmaintained/math/derivatives/derivatives-docs.factor index c6d46ba251..84f456aacf 100644 --- a/unmaintained/math/derivatives/derivatives-docs.factor +++ b/unmaintained/math/derivatives/derivatives-docs.factor @@ -1,7 +1,7 @@ USING: help.markup help.syntax math math.functions ; IN: math.derivatives -HELP: derivative ( x function -- m ) +HELP: derivative { $values { "x" "a position on the function" } { "function" "a differentiable function" } { "m" number } } { $description "Approximates the slope of the tangent line by using Ridders' " -- 2.34.1