From 2c3492a91653417095f19ac690be21fd53bd4053 Mon Sep 17 00:00:00 2001 From: John Benediktsson Date: Wed, 13 May 2015 16:09:14 -0700 Subject: [PATCH] minor cleanup to some docs. --- .../alias-analysis/alias-analysis-docs.factor | 4 +- .../block-joining/block-joining-docs.factor | 4 +- .../compiler/cfg/builder/builder-docs.factor | 8 ++-- .../cfg/gc-checks/gc-checks-docs.factor | 2 +- .../allocation/allocation-docs.factor | 6 +-- .../allocation/state/state-docs.factor | 4 +- .../cfg/liveness/liveness-docs.factor | 6 +-- .../peephole/peephole-docs.factor | 4 +- .../save-contexts/save-contexts-docs.factor | 4 +- .../codegen/gc-maps/gc-maps-docs.factor | 2 +- .../tree/debugger/debugger-docs.factor | 2 +- .../call-effect/call-effect-docs.factor | 10 ++--- .../cpu/architecture/architecture-docs.factor | 4 +- basis/deques/deques-docs.factor | 4 +- basis/dlists/dlists-docs.factor | 6 +-- basis/http/client/client-docs.factor | 44 +++++++++---------- basis/prettyprint/backend/backend-docs.factor | 4 +- basis/threads/threads-docs.factor | 4 +- basis/ui/commands/commands-docs.factor | 4 +- basis/ui/operations/operations-docs.factor | 2 +- basis/vocabs/metadata/metadata-docs.factor | 6 +-- core/assocs/assocs-docs.factor | 8 ++-- core/continuations/continuations-docs.factor | 2 +- core/io/io-docs.factor | 14 +++--- core/io/streams/c/c-docs.factor | 2 +- core/layouts/layouts-docs.factor | 2 +- core/math/math-docs.factor | 4 +- core/math/parser/parser-docs.factor | 10 ++--- core/namespaces/namespaces-docs.factor | 2 +- core/sequences/sequences-docs.factor | 34 +++++++------- core/sequences/sequences.factor | 4 +- core/vectors/vectors-docs.factor | 2 +- core/vocabs/loader/loader-docs.factor | 8 ++-- core/words/words-docs.factor | 2 +- .../alien/marshall/marshall-docs.factor | 6 +-- 35 files changed, 117 insertions(+), 117 deletions(-) diff --git a/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor b/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor index 8d09150190..5168e40aa9 100644 --- a/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor +++ b/basis/compiler/cfg/alias-analysis/alias-analysis-docs.factor @@ -1,10 +1,10 @@ -USING: compiler.cfg.instructions help.markup help.syntax ; +USING: compiler.cfg.instructions help.markup help.syntax kernel ; IN: compiler.cfg.alias-analysis HELP: useless-compare? { $values { "insn" "a " { $link ##compare } " instruction" } - { "?" "a boolean" } + { "?" boolean } } { $description "Checks if the comparison instruction is required." } ; diff --git a/basis/compiler/cfg/block-joining/block-joining-docs.factor b/basis/compiler/cfg/block-joining/block-joining-docs.factor index 3ff80b1be6..aabdb7e32d 100644 --- a/basis/compiler/cfg/block-joining/block-joining-docs.factor +++ b/basis/compiler/cfg/block-joining/block-joining-docs.factor @@ -1,8 +1,8 @@ -USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax ; +USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax kernel ; IN: compiler.cfg.block-joining HELP: join-block? -{ $values { "bb" basic-block } { "?" "a boolean" } } +{ $values { "bb" basic-block } { "?" boolean } } { $description "Whether the block can be joined with its predecessor or not." } ; HELP: join-blocks diff --git a/basis/compiler/cfg/builder/builder-docs.factor b/basis/compiler/cfg/builder/builder-docs.factor index f360f4f880..6a8b781ac0 100644 --- a/basis/compiler/cfg/builder/builder-docs.factor +++ b/basis/compiler/cfg/builder/builder-docs.factor @@ -1,6 +1,6 @@ USING: assocs compiler.cfg compiler.cfg.builder.blocks -compiler.cfg.stacks.local compiler.tree help.markup help.syntax literals math -multiline sequences vectors words ; +compiler.cfg.stacks.local compiler.tree help.markup help.syntax +kernel literals math multiline sequences vectors words ; IN: compiler.cfg.builder << @@ -72,8 +72,8 @@ HELP: emit-node HELP: trivial-branch? { $values { "nodes" "a " { $link sequence } " of " { $link node } " instances" } - { "value" "the pushed value or " { $link f } } - { "?" "a boolean" } + { "value" { $maybe "the pushed value" } } + { "?" boolean } } { $description "Checks whether nodes is a trivial branch or not. The branch is counted as trivial if all it does is push a literal value on the stack." } { $examples diff --git a/basis/compiler/cfg/gc-checks/gc-checks-docs.factor b/basis/compiler/cfg/gc-checks/gc-checks-docs.factor index 71f353c86f..172d369ea4 100644 --- a/basis/compiler/cfg/gc-checks/gc-checks-docs.factor +++ b/basis/compiler/cfg/gc-checks/gc-checks-docs.factor @@ -32,7 +32,7 @@ HELP: gc-check-offsets { $description "A basic block is divided into sections by " { $link ##call } " and " { $link ##phi } " instructions. For every section with at least one allocation, record the offset of its first instruction in a sequence." } ; HELP: insert-gc-check? -{ $values { "bb" basic-block } { "?" "a boolean" } } +{ $values { "bb" basic-block } { "?" boolean } } { $description "Whether to insert a gc check in the block or not." } ; HELP: insert-gc-checks diff --git a/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor b/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor index fde318a47d..0f3de71a62 100644 --- a/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor +++ b/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor @@ -1,6 +1,6 @@ USING: assocs compiler.cfg compiler.cfg.instructions compiler.cfg.linear-scan.allocation compiler.cfg.linear-scan.allocation.state -compiler.cfg.linear-scan.live-intervals help.markup help.syntax sequences ; +compiler.cfg.linear-scan.live-intervals help.markup help.syntax kernel sequences ; IN: compiler.cfg.linear-scan.allocation HELP: (allocate-registers) @@ -27,7 +27,7 @@ HELP: spill-at-sync-point { $values { "sync-point" sync-point } { "live-interval" live-interval-state } - { "?" "a boolean" } + { "?" boolean } } { $description "Maybe spills the live-interval at the given sync point. If the interval was spilled, then " { $link f } " is put on the stack to indicate that the interval isn't live anymore, " { $link t } " otherwise." } { $see-also spill-at-sync-point? } ; @@ -36,6 +36,6 @@ HELP: spill-at-sync-point? { $values { "sync-point" sync-point } { "live-interval" live-interval-state } - { "?" "a boolean" } + { "?" boolean } } { $description "If the live interval has a definition at a keep-dst? sync-point, don't spill." } ; diff --git a/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor b/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor index f04cbb834b..6b30670c56 100644 --- a/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor +++ b/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor @@ -2,7 +2,7 @@ USING: assocs compiler.cfg compiler.cfg.instructions compiler.cfg.linear-scan.allocation compiler.cfg.linear-scan.allocation.spilling compiler.cfg.linear-scan.live-intervals cpu.architecture heaps help.markup -help.syntax math sequences vectors ; +help.syntax kernel math sequences vectors ; IN: compiler.cfg.linear-scan.allocation.state HELP: activate-intervals @@ -66,7 +66,7 @@ HELP: progress { $see-also check-handled check-unhandled } ; HELP: register-available? -{ $values { "new" live-interval-state } { "result" "a pair" } { "?" "a boolean" } } +{ $values { "new" live-interval-state } { "result" "a pair" } { "?" boolean } } { $description "Whether the register in 'result' can be used for the given live interval." } ; HELP: registers diff --git a/basis/compiler/cfg/liveness/liveness-docs.factor b/basis/compiler/cfg/liveness/liveness-docs.factor index fea54c0760..4350773241 100644 --- a/basis/compiler/cfg/liveness/liveness-docs.factor +++ b/basis/compiler/cfg/liveness/liveness-docs.factor @@ -1,5 +1,5 @@ USING: assocs compiler.cfg compiler.cfg.def-use compiler.cfg.instructions -compiler.cfg.representations help.markup help.syntax ; +compiler.cfg.representations help.markup help.syntax kernel ; IN: compiler.cfg.liveness HELP: base-pointers @@ -31,7 +31,7 @@ HELP: live-in { $description "All the virtual registers that are live in a basic block." } ; HELP: live-in? -{ $values { "vreg" "virtual register" } { "bb" basic-block } { "?" "a boolean" } } +{ $values { "vreg" "virtual register" } { "bb" basic-block } { "?" boolean } } { $description "Whether the vreg is live in the block or not." } ; HELP: live-ins @@ -39,7 +39,7 @@ HELP: live-ins { $see-also compute-live-sets } ; HELP: lookup-base-pointer -{ $values { "vreg" "vreg" } { "vreg/f" "vreg or " { $link f } } } +{ $values { "vreg" "vreg" } { "vreg/f" { $maybe "vreg" } } } { $description "Tries to figure out what the base pointer for a vreg is. Can't use cache here because of infinite recursion inside the quotation passed to cache" } { $see-also base-pointers } ; diff --git a/basis/compiler/cfg/representations/peephole/peephole-docs.factor b/basis/compiler/cfg/representations/peephole/peephole-docs.factor index 89455a36fa..2a698acf1e 100644 --- a/basis/compiler/cfg/representations/peephole/peephole-docs.factor +++ b/basis/compiler/cfg/representations/peephole/peephole-docs.factor @@ -1,8 +1,8 @@ -USING: compiler.cfg.instructions help.markup help.syntax ; +USING: compiler.cfg.instructions help.markup help.syntax kernel ; IN: compiler.cfg.representations.peephole HELP: convert-to-zero-vector? -{ $values { "insn" insn } { "?" "a boolean" } } +{ $values { "insn" insn } { "?" boolean } } { $description "When a literal zeroes/ones vector is unboxed, we replace the " { $link ##load-reference } " with a " { $link ##zero-vector } " or " { $link ##fill-vector } " instruction since this is more efficient." } ; diff --git a/basis/compiler/cfg/save-contexts/save-contexts-docs.factor b/basis/compiler/cfg/save-contexts/save-contexts-docs.factor index 1902330a24..540a09e7ec 100644 --- a/basis/compiler/cfg/save-contexts/save-contexts-docs.factor +++ b/basis/compiler/cfg/save-contexts/save-contexts-docs.factor @@ -1,5 +1,5 @@ USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax -math sequences ; +math sequences kernel ; IN: compiler.cfg.save-contexts HELP: insert-save-contexts @@ -8,7 +8,7 @@ HELP: insert-save-contexts { $see-also context-save-needed } ; HELP: insns-needs-save-context? -{ $values { "insns" sequence } { "?" "a boolean" } } +{ $values { "insns" sequence } { "?" boolean } } { $description "Whether to insert a " { $link ##save-context } " instruction in the given instruction sequence or not." } { $see-also context-save-needed } ; diff --git a/basis/compiler/codegen/gc-maps/gc-maps-docs.factor b/basis/compiler/codegen/gc-maps/gc-maps-docs.factor index fca874cd4b..cba9d7fcbe 100644 --- a/basis/compiler/codegen/gc-maps/gc-maps-docs.factor +++ b/basis/compiler/codegen/gc-maps/gc-maps-docs.factor @@ -59,7 +59,7 @@ HELP: gc-maps { $var-description "Variable that holds a sequence of " { $link gc-map } " tuples." } ; HELP: gc-map-needed? -{ $values { "gc-map/f" "a " { $link gc-map } " or f" } { "?" "a boolean" } } +{ $values { "gc-map/f" { $maybe gc-map } } { "?" boolean } } { $description "If all slots in the gc-map are empty, then it doesn't need to be emitted." } ; HELP: serialize-gc-maps diff --git a/basis/compiler/tree/debugger/debugger-docs.factor b/basis/compiler/tree/debugger/debugger-docs.factor index 8ce7a1ad4d..70c7a0b15b 100644 --- a/basis/compiler/tree/debugger/debugger-docs.factor +++ b/basis/compiler/tree/debugger/debugger-docs.factor @@ -2,5 +2,5 @@ USING: compiler.tree help.markup help.syntax ; IN: compiler.tree.debugger HELP: #>r? -{ $values { "#shuffle" #shuffle } { "?" "a boolean" } } +{ $values { "#shuffle" #shuffle } { "?" boolean } } { $description "True if the #shuffle copies an item from the data stack to the retain stack." } ; diff --git a/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor b/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor index 7493f23687..aaab9b598a 100644 --- a/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor +++ b/basis/compiler/tree/propagation/call-effect/call-effect-docs.factor @@ -1,13 +1,13 @@ USING: combinators.private compiler.units effects help.markup help.syntax -quotations ; +kernel quotations words ; IN: compiler.tree.propagation.call-effect HELP: already-inlined-quot? -{ $values { "quot" quotation } { "?" "a boolean" } } +{ $values { "quot" quotation } { "?" boolean } } { $description "Some bookkeeping to make sure that crap like [ dup curry call( quot -- ) ] dup curry call( quot -- ) ] doesn't hang the compiler." } ; HELP: cached-effect-valid? -{ $values { "quot" quotation } { "?" "a boolean" } } +{ $values { "quot" quotation } { "?" boolean } } { $description { $link t } " if the cached effect is valid." } ; HELP: call-effect-ic @@ -23,11 +23,11 @@ HELP: call-effect-slow>quot { $description "Creates a quotation which wraps " { $link call-effect-unsafe } "." } ; HELP: call-effect-unsafe? -{ $values { "quot" quotation } { "effect" effect } { "?" "a boolean" } } +{ $values { "quot" quotation } { "effect" effect } { "?" boolean } } { $description "Checks if the given effect is safe with regards to the quotation." } ; HELP: update-inline-cache -{ $values { "word/quot" "word or quotation" } { "ic" inline-cache } } +{ $values { "word/quot" { $or word quotation } } { "ic" inline-cache } } { $description "Sets the inline caches " { $slot "value" } " to the given word/quot and updates its " { $slot "counter" } " to the value of the " { $link effect-counter } "." } ; ARTICLE: "compiler.tree.propagation.call-effect" "Expansions of call( and execute( words" diff --git a/basis/cpu/architecture/architecture-docs.factor b/basis/cpu/architecture/architecture-docs.factor index 961614c933..de9bee0301 100644 --- a/basis/cpu/architecture/architecture-docs.factor +++ b/basis/cpu/architecture/architecture-docs.factor @@ -259,7 +259,7 @@ HELP: %write-barrier { $examples { $unchecked-example $[ ex-%write-barrier ] } } ; HELP: test-instruction? -{ $values { "?" "a boolean" } } +{ $values { "?" boolean } } { $description "Does the current architecture have a test instruction? Used on x86 to rewrite some " { $link CMP } " instructions to less expensive " { $link TEST } "s." } ; HELP: fused-unboxing? @@ -271,7 +271,7 @@ HELP: return-regs { $description "What registers that will be used for function return values of which class." } ; HELP: return-struct-in-registers? -{ $values { "c-type" class } { "?" "a boolean" } } +{ $values { "c-type" class } { "?" boolean } } { $description "Whether the size of the struct is so small that it will be returned in registers or not." } ; HELP: stack-cleanup diff --git a/basis/deques/deques-docs.factor b/basis/deques/deques-docs.factor index 9773e7ceb5..cd90a357e7 100644 --- a/basis/deques/deques-docs.factor +++ b/basis/deques/deques-docs.factor @@ -72,7 +72,7 @@ HELP: peek-front { $errors "Throws an error if the deque is empty." } ; HELP: ?peek-front -{ $values { "deque" deque } { "obj/f" "an object or " { $link f } } } +{ $values { "deque" deque } { "obj/f" { $maybe object } } } { $description "A forgiving version of " { $link peek-front } ". If the deque is empty, returns " { $link f } "." } ; HELP: pop-front @@ -95,7 +95,7 @@ HELP: peek-back { $errors "Throws an error if the deque is empty." } ; HELP: ?peek-back -{ $values { "deque" deque } { "obj/f" "an object or " { $link f } } } +{ $values { "deque" deque } { "obj/f" { $maybe object } } } { $description "A forgiving version of " { $link peek-back } ". If the deque is empty, returns " { $link f } "." } ; HELP: pop-back diff --git a/basis/dlists/dlists-docs.factor b/basis/dlists/dlists-docs.factor index 8138feee6a..508116816a 100644 --- a/basis/dlists/dlists-docs.factor +++ b/basis/dlists/dlists-docs.factor @@ -40,7 +40,7 @@ HELP: { $description "Creates a new " { $link search-deque } " backed by a " { $link dlist } ", with a " { $link hashtable } " for fast membership tests." } ; HELP: dlist-find -{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } { "?" boolean } } +{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" { $maybe object } } { "?" boolean } } { $description "Applies the quotation to each element of the " { $link dlist } " in turn, until it outputs a true value or the end of the " { $link dlist } " is reached. Outputs either the object it found or " { $link f } ", and a boolean which is true if an object is found." } { $notes "Returns a boolean to allow dlists to store " { $link f } "." $nl @@ -58,12 +58,12 @@ HELP: dlist-any? { $notes "This operation is O(n)." } ; HELP: delete-node-if* -{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } { "?" boolean } } +{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" { $maybe object } } { "?" boolean } } { $description "Calls " { $link dlist-find } " on the " { $link dlist } " and deletes the node returned, if any. Returns the value of the deleted node and a boolean to allow the deleted value to distinguished from " { $link f } ", for nothing deleted." } { $notes "This operation is O(n)." } ; HELP: delete-node-if -{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } } +{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" { $maybe object } } } { $description "Like " { $link delete-node-if* } " but cannot distinguish from deleting a node whose value is " { $link f } " or not deleting an element." } { $notes "This operation is O(n)." } ; diff --git a/basis/http/client/client-docs.factor b/basis/http/client/client-docs.factor index 3628f9942b..e7b661b038 100644 --- a/basis/http/client/client-docs.factor +++ b/basis/http/client/client-docs.factor @@ -11,112 +11,112 @@ HELP: too-many-redirects { $error-description "Thrown by " { $link http-request } " if the server returns a chain of than " { $link max-redirects } " redirections." } ; HELP: -{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } } +{ $values { "url" { $or url string } } { "request" request } } { $description "Constructs an HTTP GET request for retrieving the URL." } { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ; HELP: -{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "request" request } } +{ $values { "post-data" object } { "url" { $or url string } } { "request" request } } { $description "Constructs an HTTP POST request for submitting post data to the URL." } { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ; HELP: -{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } } +{ $values { "url" { $or url string } } { "request" request } } { $description "Constructs an HTTP HEAD request for retrieving the URL." } { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ; HELP: -{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } } +{ $values { "url" { $or url string } } { "request" request } } { $description "Constructs an HTTP DELETE request for the requested URL." } { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ; HELP: -{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } } +{ $values { "url" { $or url string } } { "request" request } } { $description "Constructs an HTTP OPTIONS request for the requested URL." } { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ; HELP: -{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } } +{ $values { "url" { $or url string } } { "request" request } } { $description "Constructs an HTTP TRACE request for the requested URL." } { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ; HELP: download -{ $values { "url" "a " { $link url } " or " { $link string } } } +{ $values { "url" { $or url string } } } { $description "Downloads the contents of the URL to a file in the " { $link current-directory } " having the same file name." } { $errors "Throws an error if the HTTP request fails." } ; HELP: download-to -{ $values { "url" "a " { $link url } " or " { $link string } } { "file" "a pathname string" } } +{ $values { "url" { $or url string } } { "file" "a pathname string" } } { $description "Downloads the contents of the URL to a file with the given pathname." } { $errors "Throws an error if the HTTP request fails." } ; HELP: ?download-to -{ $values { "url" "a " { $link url } " or " { $link string } } { "file" "a pathname string" } } +{ $values { "url" { $or url string } } { "file" "a pathname string" } } { $description "Version of " { $link download-to } " that only downloads if " { $snippet "file" } " does not exist." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-get -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Downloads the contents of a URL." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-get* -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Downloads the contents of a URL, but does not check the HTTP response code for success." } ; { http-get http-get* } related-words HELP: http-post -{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP POST request." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-post* -{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP POST request, but does not check the HTTP response code for success." } ; { http-post http-post* } related-words HELP: http-put -{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP PUT request." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-put* -{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP PUT request, but does not check the HTTP response code for success." } ; { http-put http-put* } related-words HELP: http-head -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Same as " { $link http-get } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-head* -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Same as " { $link http-get* } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." } ; { http-head http-head* } related-words HELP: http-delete -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Requests that the origin server delete the resource identified by the URL." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-delete* -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Requests that the origin server delete the resource identified by the URL, but does not check the HTTP response code for success." } ; { http-delete http-delete* } related-words HELP: http-options -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP OPTIONS request." } { $errors "Throws an error if the HTTP request fails." } ; HELP: http-options* -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP OPTIONS request, but does not check the HTTP response code for success." } ; { http-options http-options* } related-words @@ -127,7 +127,7 @@ HELP: http-trace { $errors "Throws an error if the HTTP request fails." } ; HELP: http-trace* -{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } } +{ $values { "url" { $or url string } } { "response" response } { "data" sequence } } { $description "Submits an HTTP TRACE request, but does not check the HTTP response code for success." } ; { http-trace http-trace* } related-words diff --git a/basis/prettyprint/backend/backend-docs.factor b/basis/prettyprint/backend/backend-docs.factor index 250fbe61b0..e9b536a83f 100644 --- a/basis/prettyprint/backend/backend-docs.factor +++ b/basis/prettyprint/backend/backend-docs.factor @@ -1,4 +1,4 @@ -USING: help.markup help.syntax kernel prettyprint.config +USING: help.markup help.syntax kernel math prettyprint.config prettyprint.custom sequences strings words ; IN: prettyprint.backend @@ -37,7 +37,7 @@ HELP: check-recursion $prettyprinting-note ; HELP: do-length-limit -{ $values { "seq" sequence } { "trimmed" "a trimmed sequence" } { "n/f" "an integer or " { $link f } } } +{ $values { "seq" sequence } { "trimmed" "a trimmed sequence" } { "n/f" { $maybe integer } } } { $description "If the " { $link length-limit } " is set and the sequence length exceeds this limit, trims the sequence and outputs a the number of elements which were chopped off the end. Otherwise outputs " { $link f } "." } $prettyprinting-note ; diff --git a/basis/threads/threads-docs.factor b/basis/threads/threads-docs.factor index 7d58d6f635..53e0e67711 100644 --- a/basis/threads/threads-docs.factor +++ b/basis/threads/threads-docs.factor @@ -111,7 +111,7 @@ HELP: sleep-queue { $var-description "A " { $link min-heap } " storing the queue of sleeping threads." } ; HELP: sleep-time -{ $values { "nanos/f" "a non-negative integer or " { $link f } } } +{ $values { "nanos/f" { $maybe "a non-negative integer" } } } { $description "Returns the time until the next sleeping thread is scheduled to wake up, which could be zero if there are threads in the run queue, or threads which need to wake up right now. If there are no runnable or sleeping threads, returns " { $link f } "." } ; HELP: stop @@ -121,7 +121,7 @@ HELP: yield { $description "Adds the current thread to the end of the run queue, and switches to the next runnable thread." } ; HELP: sleep-until -{ $values { "n/f" "a non-negative integer or " { $link f } } } +{ $values { "n/f" { $maybe "a non-negative integer" } } } { $description "Suspends the current thread until the given nanosecond count, returned by " { $link nano-count } ", is reached, or indefinitely if a value of " { $link f } " is passed in." $nl "Other threads may interrupt the sleep by calling " { $link interrupt } "." } ; diff --git a/basis/ui/commands/commands-docs.factor b/basis/ui/commands/commands-docs.factor index 135ef00f84..d3ed8156bc 100644 --- a/basis/ui/commands/commands-docs.factor +++ b/basis/ui/commands/commands-docs.factor @@ -48,7 +48,7 @@ HELP: invoke-command { invoke-command +nullary+ } related-words HELP: command-name -{ $values { "command" "a command" } { "str" "a string" } } +{ $values { "command" "a command" } { "str" string } } { $description "Outputs a human-readable name for the command." } { $examples { $example @@ -61,7 +61,7 @@ HELP: command-name } ; HELP: command-description -{ $values { "command" "a command" } { "str/f" "a string or " { $link f } } } +{ $values { "command" "a command" } { "str/f" { $maybe string } } } { $description "Outputs the command's description." } ; { command-description +description+ } related-words diff --git a/basis/ui/operations/operations-docs.factor b/basis/ui/operations/operations-docs.factor index 26bf248174..07ef9dd116 100644 --- a/basis/ui/operations/operations-docs.factor +++ b/basis/ui/operations/operations-docs.factor @@ -30,7 +30,7 @@ $nl } } ; HELP: operation-gesture -{ $values { "operation" operation } { "gesture" "a gesture or " { $link f } } } +{ $values { "operation" operation } { "gesture" { $maybe "a gesture" } } } { $description "Outputs the keyboard gesture associated with the operation." } ; HELP: operations diff --git a/basis/vocabs/metadata/metadata-docs.factor b/basis/vocabs/metadata/metadata-docs.factor index c3dce45c09..f13c93379f 100644 --- a/basis/vocabs/metadata/metadata-docs.factor +++ b/basis/vocabs/metadata/metadata-docs.factor @@ -45,7 +45,7 @@ ARTICLE: "vocabs.metadata" "Vocabulary metadata" ABOUT: "vocabs.metadata" HELP: vocab-file-contents -{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "seq" "a sequence of lines, or " { $link f } } } +{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "seq" { $maybe "a sequence of lines" } } } { $description "Outputs the contents of the file named " { $snippet "name" } " from the vocabulary's directory, or " { $link f } " if the file does not exist." } ; HELP: set-vocab-file-contents @@ -53,11 +53,11 @@ HELP: set-vocab-file-contents { $description "Stores a sequence of lines to the file named " { $snippet "name" } " from the vocabulary's directory." } ; HELP: vocab-summary -{ $values { "vocab" "a vocabulary specifier" } { "summary" "a string or " { $link f } } } +{ $values { "vocab" "a vocabulary specifier" } { "summary" { $maybe string } } } { $description "Outputs a one-line string description of the vocabulary's intended purpose from the " { $snippet "summary.txt" } " file in the vocabulary's directory. Outputs " { $link f } " if the file does not exist." } ; HELP: set-vocab-summary -{ $values { "string" "a string or " { $link f } } { "vocab" "a vocabulary specifier" } } +{ $values { "string" { $maybe string } } { "vocab" "a vocabulary specifier" } } { $description "Stores a one-line string description of the vocabulary to the " { $snippet "summary.txt" } " file in the vocabulary's directory." } ; HELP: vocab-tags diff --git a/core/assocs/assocs-docs.factor b/core/assocs/assocs-docs.factor index b7bd5713b1..96300ac86d 100644 --- a/core/assocs/assocs-docs.factor +++ b/core/assocs/assocs-docs.factor @@ -360,16 +360,16 @@ HELP: assoc-hashcode { $notes "Custom assoc implementations should use this word to implement a method for the " { $link hashcode* } " generic word." } ; HELP: assoc-stack -{ $values { "key" "a key" } { "seq" "a sequence of assocs" } { "value" "a value or " { $link f } } } +{ $values { "key" "a key" } { "seq" "a sequence of assocs" } { "value" { $maybe "a value" } } } { $description "Searches for the key in successive elements of the sequence, starting from the end. If an assoc containing the key is found, the associated value is output. If no assoc contains the key, outputs " { $link f } "." } { $notes "This word is used to implement abstractions such as nested scopes; if the sequence is a stack represented by a vector, then the most recently pushed assoc -- the innermost scope -- will be searched first." } ; HELP: value-at* -{ $values { "value" object } { "assoc" assoc } { "key/f" "the key associated to the value, or " { $link f } } { "?" boolean } } +{ $values { "value" object } { "assoc" assoc } { "key/f" { $maybe "the key associated to the value" } } { "?" boolean } } { $description "Looks up the key associated with a value. The boolean flag can decide between the case of a missing key, and a key of " { $link f } "." } ; HELP: value-at -{ $values { "value" object } { "assoc" assoc } { "key/f" "the key associated to the value, or " { $link f } } } +{ $values { "value" object } { "assoc" assoc } { "key/f" { $maybe "the key associated to the value" } } } { $description "Looks up the key associated with a value. No distinction is made between a missing key and a key set to " { $link f } "." } ; HELP: value? @@ -377,7 +377,7 @@ HELP: value? { $description "Tests if an assoc contains at least one key with the given value." } ; HELP: delete-at* -{ $values { "key" "a key" } { "assoc" assoc } { "old" "the previous value or " { $link f } } { "?" boolean } } +{ $values { "key" "a key" } { "assoc" assoc } { "old" { $maybe "the previous value" } } { "?" boolean } } { $description "Removes an entry from the assoc and outputs the previous value together with a boolean indicating whether it was present." } { $side-effects "assoc" } ; diff --git a/core/continuations/continuations-docs.factor b/core/continuations/continuations-docs.factor index c86093507e..ca58087a12 100644 --- a/core/continuations/continuations-docs.factor +++ b/core/continuations/continuations-docs.factor @@ -184,7 +184,7 @@ HELP: ignore-errors { $description "Calls the quotation. If an exception is thrown in the dynamic extent of the quotation, restores the data stack and returns." } ; HELP: in-callback? -{ $values { "?" "a boolean" } } +{ $values { "?" boolean } } { $description "t if Factor is currently executing a callback." } ; HELP: rethrow diff --git a/core/io/io-docs.factor b/core/io/io-docs.factor index 67fb5757c1..1e0267544a 100644 --- a/core/io/io-docs.factor +++ b/core/io/io-docs.factor @@ -27,13 +27,13 @@ HELP: stream-element-type { $contract "Outputs one of " { $link +byte+ } " or " { $link +character+ } "." } ; HELP: stream-readln -{ $values { "stream" "an input stream" } { "str/f" "a string or " { $link f } } } +{ $values { "stream" "an input stream" } { "str/f" { $maybe string } } } { $contract "Reads a line of input from the stream. Outputs " { $link f } " on stream exhaustion." } { $notes "Most code only works on one stream at a time and should instead use " { $link readln } "; see " { $link "stdio" } "." } $io-error ; HELP: stream-read1 -{ $values { "stream" "an input stream" } { "elt" "an element or " { $link f } } } +{ $values { "stream" "an input stream" } { "elt" { $maybe "an element" } } } { $contract "Reads an element from the stream. Outputs " { $link f } " on stream exhaustion." } { $notes "Most code only works on one stream at a time and should instead use " { $link read1 } "; see " { $link "stdio" } "." } $io-error ; @@ -62,7 +62,7 @@ HELP: stream-read-into $io-error ; HELP: stream-read-until -{ $values { "seps" string } { "stream" "an input stream" } { "seq" { $or byte-array string f } } { "sep/f" "a character or " { $link f } } } +{ $values { "seps" string } { "stream" "an input stream" } { "seq" { $or byte-array string f } } { "sep/f" { $maybe "a character" } } } { $contract "Reads elements from the stream, until the first occurrence of a separator character, or stream exhaustion. In the former case, the separator is pushed on the stack, and is not part of the output string. In the latter case, the entire stream contents are output, along with " { $link f } "." } { $notes "Most code only works on one stream at a time and should instead use " { $link read-until } "; see " { $link "stdio" } "." } $io-error ; @@ -157,7 +157,7 @@ HELP: stream-seekable? HELP: stream-length { $values - { "stream" "a stream" } { "n/f" "an integer or " { $link f } } + { "stream" "a stream" } { "n/f" { $maybe integer } } } { $description "Returns the length of the data supplied by " { $snippet "stream" } ", or " { $link f } " if the stream is not seekable or has unknown length." } { $notes "Stream seeking is not supported on streams that do not have a known length, e.g. TCP/IP streams." } ; @@ -208,12 +208,12 @@ HELP: error-stream { $var-description "Holds an error stream." } ; HELP: readln -{ $values { "str/f" "a string or " { $link f } } } +{ $values { "str/f" { $maybe string } } } { $description "Reads a line of input from " { $link input-stream } ". Outputs " { $link f } " on stream exhaustion." } $io-error ; HELP: read1 -{ $values { "elt" "an element or " { $link f } } } +{ $values { "elt" { $maybe "an element" } } } { $description "Reads an element from " { $link input-stream } ". Outputs " { $link f } " on stream exhaustion." } $io-error ; @@ -223,7 +223,7 @@ HELP: read $io-error ; HELP: read-until -{ $values { "seps" string } { "seq" { $or byte-array string f } } { "sep/f" "a character or " { $link f } } } +{ $values { "seps" string } { "seq" { $or byte-array string f } } { "sep/f" { $maybe "a character" } } } { $contract "Reads elements from " { $link input-stream } " until the first occurrence of a separator, or stream exhaustion. In the former case, the separator character is pushed on the stack, and is not part of the output. In the latter case, the entire stream contents are output, along with " { $link f } "." } $io-error ; diff --git a/core/io/streams/c/c-docs.factor b/core/io/streams/c/c-docs.factor index 531cc9678e..bd87d80295 100644 --- a/core/io/streams/c/c-docs.factor +++ b/core/io/streams/c/c-docs.factor @@ -58,7 +58,7 @@ HELP: fclose { $description "Closes a C FILE* handle." } ; HELP: fgetc -{ $values { "alien" "a C FILE* handle" } { "byte/f" "an integer from 0 to 255 or " { $link f } } } +{ $values { "alien" "a C FILE* handle" } { "byte/f" { $maybe "an integer from 0 to 255" } } } { $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." } ; diff --git a/core/layouts/layouts-docs.factor b/core/layouts/layouts-docs.factor index d330f52519..4d6d3e6e31 100644 --- a/core/layouts/layouts-docs.factor +++ b/core/layouts/layouts-docs.factor @@ -14,7 +14,7 @@ HELP: num-types { $var-description "Number of distinct built-in types. This is one more than the maximum value from the " { $link tag } " primitive." } ; HELP: type-number -{ $values { "class" class } { "n" "an integer or " { $link f } } } +{ $values { "class" class } { "n" { $maybe integer } } } { $description "Outputs the built-in type number instances of " { $link class } ". Will output " { $link f } " if this is not a built-in class." } { $see-also builtin-class } ; diff --git a/core/math/math-docs.factor b/core/math/math-docs.factor index befa11c7e1..2c434cff83 100644 --- a/core/math/math-docs.factor +++ b/core/math/math-docs.factor @@ -423,12 +423,12 @@ HELP: all-integers? { $notes "This word is used to implement " { $link all? } "." } ; HELP: find-integer -{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" "an integer or " { $link f } } } +{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" { $maybe integer } } } { $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } ". Iteration stops when the quotation outputs a true value or the end is reached. If the quotation yields a true value for some integer, this word outputs that integer. Otherwise, this word outputs " { $link f } "." } { $notes "This word is used to implement " { $link find } "." } ; HELP: find-last-integer -{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" "an integer or " { $link f } } } +{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" { $maybe integer } } } { $description "Applies the quotation to each integer from " { $snippet "n" } " down to 0, inclusive. Iteration stops when the quotation outputs a true value or 0 is reached. If the quotation yields a true value for some integer, the word outputs that integer. Otherwise, the word outputs " { $link f } "." } { $notes "This word is used to implement " { $link find-last } "." } ; diff --git a/core/math/parser/parser-docs.factor b/core/math/parser/parser-docs.factor index fb200ce60c..9cefe52319 100644 --- a/core/math/parser/parser-docs.factor +++ b/core/math/parser/parser-docs.factor @@ -44,7 +44,7 @@ HELP: digit> { $notes "This is one of the factors of " { $link string>number } "." } ; HELP: base> -{ $values { "str" string } { "radix" "an integer between 2 and 16" } { "n/f" "a real number or " { $link f } } } +{ $values { "str" string } { "radix" "an integer between 2 and 16" } { "n/f" { $maybe real } } } { $description "Creates a real number from a string representation with the given radix. The radix for floating point literals can be either base 10 or base 16." $nl "Outputs " { $link f } " if the string does not represent a number." } ; @@ -52,7 +52,7 @@ $nl { >base base> } related-words HELP: string>number -{ $values { "str" string } { "n/f" "a real number or " { $link f } } } +{ $values { "str" string } { "n/f" { $maybe real } } } { $description "Creates a real number from a string representation of a number in base 10." $nl "Outputs " { $link f } " if the string does not represent a number." } ; @@ -60,7 +60,7 @@ $nl { string>number number>string } related-words HELP: bin> -{ $values { "str" string } { "n/f" "a real number or " { $link f } } } +{ $values { "str" string } { "n/f" { $maybe real } } } { $description "Creates a real number from a string representation of a number in base 2." $nl "Outputs " { $link f } " if the string does not represent a number." } ; @@ -68,7 +68,7 @@ $nl { >bin bin> .b } related-words HELP: oct> -{ $values { "str" string } { "n/f" "a real number or " { $link f } } } +{ $values { "str" string } { "n/f" { $maybe real } } } { $description "Creates a real number from a string representation of a number in base 8." $nl "Outputs " { $link f } " if the string does not represent a number." } ; @@ -76,7 +76,7 @@ $nl { >oct oct> .o } related-words HELP: hex> -{ $values { "str" string } { "n/f" "a real number or " { $link f } } } +{ $values { "str" string } { "n/f" { $maybe real } } } { $description "Creates a real number from a string representation of a number in base 16." $nl "Outputs " { $link f } " if the string does not represent a number." } ; diff --git a/core/namespaces/namespaces-docs.factor b/core/namespaces/namespaces-docs.factor index 0c77bbb3ce..0b2928f5b1 100644 --- a/core/namespaces/namespaces-docs.factor +++ b/core/namespaces/namespaces-docs.factor @@ -65,7 +65,7 @@ $nl ABOUT: "namespaces" HELP: get -{ $values { "variable" "a variable, by convention a symbol" } { "value" "the value, or " { $link f } } } +{ $values { "variable" "a variable, by convention a symbol" } { "value" { $maybe "the value" } } } { $description "Searches the name stack for a namespace containing the variable, and outputs the associated value. If no such namespace is found, outputs " { $link f } "." } ; HELP: set diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor index 9504b360c4..308509d8ac 100644 --- a/core/sequences/sequences-docs.factor +++ b/core/sequences/sequences-docs.factor @@ -166,16 +166,16 @@ HELP: bounds-check? { $description "Tests if the index is within the bounds of the sequence." } ; HELP: bounds-error -{ $values { "n" "a positive integer" } { "seq" sequence } } +{ $values { "n" integer } { "seq" sequence } } { $description "Throws a " { $link bounds-error } "." } { $error-description "Thrown by " { $link nth } ", " { $link set-nth } " and " { $link set-length } " if the given index lies beyond the bounds of the sequence." } ; HELP: bounds-check -{ $values { "n" "a positive integer" } { "seq" sequence } } +{ $values { "n" integer } { "seq" sequence } } { $description "Throws an error if " { $snippet "n" } " is negative or if it is greater than or equal to the length of " { $snippet "seq" } ". Otherwise the two inputs remain on the stack." } ; HELP: ?nth -{ $values { "n" integer } { "seq" sequence } { "elt/f" "an object or " { $link f } } } +{ $values { "n" integer } { "seq" sequence } { "elt/f" { $maybe object } } } { $description "A forgiving version of " { $link nth } ". If the index is out of bounds, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ; HELP: ?set-nth @@ -183,7 +183,7 @@ HELP: ?set-nth { $description "A forgiving version of " { $link set-nth } ". If the index is out of bounds, does nothing." } ; HELP: ?first -{ $values { "seq" sequence } { "elt/f" "an object or " { $link f } } } +{ $values { "seq" sequence } { "elt/f" { $maybe object } } } { $description "A forgiving version of " { $link first } ". If the sequence is empty, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } { $examples "On an empty sequence:" @@ -200,11 +200,11 @@ HELP: ?first HELP: ?second -{ $values { "seq" sequence } { "elt/f" "an object or " { $link f } } } +{ $values { "seq" sequence } { "elt/f" { $maybe object } } } { $description "A forgiving version of " { $link second } ". If the sequence has less than two elements, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ; HELP: ?last -{ $values { "seq" sequence } { "elt/f" "an object or " { $link f } } } +{ $values { "seq" sequence } { "elt/f" { $maybe object } } } { $description "A forgiving version of " { $link last } ". If the sequence is empty, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ; HELP: nth-unsafe @@ -456,35 +456,35 @@ HELP: find-from { $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } - { "i" "the index of the first match, or " { $link f } } - { "elt" "the first matching element, or " { $link f } } } + { "i" { $maybe "the index of the first match" } } + { "elt" { $maybe "the first matching element" } } } { $description "Applies the quotation to each element of the sequence in turn, until it outputs a true value or the end of the sequence is reached. If the quotation yields a true value for some sequence element, the word outputs the element index and the element itself. Otherwise, the word outputs an index of " { $link f } " and " { $link f } " as the element." } ; HELP: find-last -{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" "the index of the first match, or f" } { "elt" "the first matching element, or " { $link f } } } +{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" { $maybe "the index of the first match" } } { "elt" { $maybe "the first matching element" } } } { $description "A simpler variant of " { $link find-last-from } " where the starting index is one less than the length of the sequence." } ; HELP: find-last-from -{ $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" "the index of the first match, or f" } { "elt" "the first matching element, or " { $link f } } } +{ $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" { $maybe "the index of the first match" } } { "elt" { $maybe "the first matching element" } } } { $description "Applies the quotation to each element of the sequence in reverse order, until it outputs a true value or the start of the sequence is reached. If the quotation yields a true value for some sequence element, the word outputs the element index and the element itself. Otherwise, the word outputs an index of " { $link f } " and " { $link f } " as the element." } ; HELP: find-index { $values { "seq" sequence } { "quot" { $quotation ( ... elt i -- ... ? ) } } - { "i" "the index of the first match, or " { $link f } } - { "elt" "the first matching element, or " { $link f } } } + { "i" { $maybe "the index of the first match" } } + { "elt" { $maybe "the first matching element" } } } { $description "A varient of " { $link find } " where the quotation takes both an element and its index." } ; HELP: find-index-from { $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation ( ... elt i -- ... ? ) } } - { "i" "the index of the first match, or " { $link f } } - { "elt" "the first matching element, or " { $link f } } } + { "i" { $maybe "the index of the first match" } } + { "elt" { $maybe "the first matching element" } } } { $description "A varient of " { $link find-from } " where the quotation takes both an element and its index." } ; HELP: map-find -{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... result/f ) } } { "result" "the first non-false result of the quotation" } { "elt" "the first matching element, or " { $link f } } } +{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... result/f ) } } { "result" "the first non-false result of the quotation" } { "elt" { $maybe "the first matching element" } } } { $description "Applies the quotation to each element of the sequence, until the quotation outputs a true value. If the quotation ever yields a result which is not " { $link f } ", then the value is output, along with the element of the sequence which yielded this." } ; HELP: any? @@ -1132,12 +1132,12 @@ HELP: product { $description "Outputs the product of all elements of " { $snippet "seq" } ". Outputs one given an empty sequence." } ; HELP: infimum -{ $values { "seq" "a sequence of real numbers" } { "n" number } } +{ $values { "seq" "a sequence of real numbers" } { "elt" object } } { $description "Outputs the least element of " { $snippet "seq" } "." } { $errors "Throws an error if the sequence is empty." } ; HELP: supremum -{ $values { "seq" "a sequence of real numbers" } { "n" number } } +{ $values { "seq" "a sequence of real numbers" } { "elt" object } } { $description "Outputs the greatest element of " { $snippet "seq" } "." } { $errors "Throws an error if the sequence is empty." } ; diff --git a/core/sequences/sequences.factor b/core/sequences/sequences.factor index bb132b8e5b..f680671559 100644 --- a/core/sequences/sequences.factor +++ b/core/sequences/sequences.factor @@ -1038,9 +1038,9 @@ M: repetition sum [ elt>> ] [ len>> ] bi * ; inline : product ( seq -- n ) 1 [ * ] binary-reduce ; -: infimum ( seq -- n ) [ ] [ min ] map-reduce ; +: infimum ( seq -- elt ) [ ] [ min ] map-reduce ; -: supremum ( seq -- n ) [ ] [ max ] map-reduce ; +: supremum ( seq -- elt ) [ ] [ max ] map-reduce ; : map-sum ( ... seq quot: ( ... elt -- ... n ) -- ... n ) [ 0 ] 2dip [ dip + ] curry [ swap ] prepose each ; inline diff --git a/core/vectors/vectors-docs.factor b/core/vectors/vectors-docs.factor index 035d131dd2..615a52c637 100644 --- a/core/vectors/vectors-docs.factor +++ b/core/vectors/vectors-docs.factor @@ -43,7 +43,7 @@ HELP: 1vector { $description "Create a new vector with one element." } ; HELP: ?push -{ $values { "elt" object } { "seq/f" "a resizable mutable sequence, or " { $link f } } { "seq" "a resizable mutable sequence" } } +{ $values { "elt" object } { "seq/f" { $maybe "a resizable mutable sequence" } } { "seq" "a resizable mutable sequence" } } { $description "If the given sequence is " { $link f } ", creates and outputs a new one-element vector holding " { $snippet "elt" } ". Otherwise, pushes " { $snippet "elt" } " onto the given sequence." } { $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." } { $side-effects "seq" } ; diff --git a/core/vocabs/loader/loader-docs.factor b/core/vocabs/loader/loader-docs.factor index f50bdd6d0d..e4be81052f 100755 --- a/core/vocabs/loader/loader-docs.factor +++ b/core/vocabs/loader/loader-docs.factor @@ -1,5 +1,5 @@ USING: vocabs vocabs.loader.private help.markup help.syntax -words strings io ; +words strings io hashtables ; IN: vocabs.loader ARTICLE: "add-vocab-roots" "Working with code outside of the Factor source tree" @@ -72,7 +72,7 @@ $nl ABOUT: "vocabs.loader" HELP: load-vocab -{ $values { "name" "a string" } { "vocab" "a hashtable or " { $link f } } } +{ $values { "name" "a string" } { "vocab" { $maybe hashtable } } } { $description "Attempts to load a vocabulary from disk, or looks up the vocabulary in the dictionary, and then outputs that vocabulary object." } ; HELP: vocab-main @@ -123,9 +123,9 @@ HELP: run { $description "Runs a vocabulary's main entry point. The main entry point is set with the " { $link POSTPONE: MAIN: } " parsing word." } ; HELP: vocab-source-path -{ $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } } +{ $values { "vocab" "a vocabulary specifier" } { "path/f" { $maybe "a pathname string" } } } { $description "Outputs a pathname where source code for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ; HELP: vocab-docs-path -{ $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } } +{ $values { "vocab" "a vocabulary specifier" } { "path/f" { $maybe "a pathname string" } } } { $description "Outputs a pathname where the documentation for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ; diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index 1f23d5cbbf..b4651651d4 100644 --- a/core/words/words-docs.factor +++ b/core/words/words-docs.factor @@ -346,7 +346,7 @@ HELP: deprecated? { $notes "Outputs " { $link f } " if the object is not a word." } ; HELP: inline? -{ $values { "obj" object } { "?" "a boolean" } } +{ $values { "obj" object } { "?" boolean } } { $description "Tests if an object is " { $link POSTPONE: inline } "." } { $notes "Outputs " { $link f } " if the object is not a word." } ; diff --git a/unmaintained/alien/marshall/marshall-docs.factor b/unmaintained/alien/marshall/marshall-docs.factor index 2e5a5c182b..519fe99378 100644 --- a/unmaintained/alien/marshall/marshall-docs.factor +++ b/unmaintained/alien/marshall/marshall-docs.factor @@ -389,21 +389,21 @@ HELP: struct-wrapper HELP: unmarshall-bool { $values { "n" number } - { "?" "a boolean" } + { "?" boolean } } { $description "Unmarshalls a number to a boolean." } ; HELP: unmarshall-bool* { $values { "alien" alien } - { "?" "a boolean" } + { "?" boolean } } { $description "Unmarshalls a C pointer to a boolean." } ; HELP: unmarshall-bool*-free { $values { "alien" alien } - { "?" "a boolean" } + { "?" boolean } } { $description "Unmarshalls a C pointer to a boolean and frees the pointer." } ; -- 2.34.1