From: Björn Lindqvist Date: Sun, 13 Apr 2014 23:26:43 +0000 (+0200) Subject: Docs: fixed doc example errors triggered by help-lint and added with-disposal where... X-Git-Tag: 0.97~681 X-Git-Url: https://gitweb.factorcode.org/gitweb.cgi?p=factor.git;a=commitdiff_plain;h=b72fa3ba0a5f9d58e527900fbcb56a40787adc13 Docs: fixed doc example errors triggered by help-lint and added with-disposal where applicable --- diff --git a/basis/io/buffers/buffers-docs.factor b/basis/io/buffers/buffers-docs.factor index c2bf6e0f67..d9fbc683c3 100644 --- a/basis/io/buffers/buffers-docs.factor +++ b/basis/io/buffers/buffers-docs.factor @@ -49,7 +49,7 @@ $nl HELP: { $values { "n" "a non-negative integer" } { "buffer" buffer } } -{ $description "Creates a buffer with an initial capacity of " { $snippet "n" } " bytes." } ; +{ $description "Allocates a buffer with an initial capacity of " { $snippet "n" } " bytes." } ; HELP: buffer-reset { $values { "n" "a non-negative integer" } { "buffer" buffer } } @@ -72,8 +72,8 @@ HELP: buffer-read { $description "Collects a byte array of " { $snippet "n" } " bytes starting from the buffer's current position, and advances the position accordingly. If there are less than " { $snippet "n" } " bytes available, the output is truncated." } { $examples { $example - "USING: io.buffers ;" - "5 100 B{ 7 14 21 } over >buffer buffer-read ." + "USING: destructors io.buffers kernel prettyprint ;" + "5 100 [ B{ 7 14 21 } over >buffer buffer-read ] with-disposal ." "B{ 7 14 21 }" } } ; @@ -83,8 +83,8 @@ HELP: buffer-length { $description "Outputs the number of unconsumed bytes in the buffer." } { $examples { $example - "USING: io.buffers ;" - "100 B{ 7 14 21 } over >buffer buffer-length ." + "USING: destructors io.buffers kernel prettyprint ;" + "100 [ B{ 7 14 21 } over >buffer buffer-length ] with-disposal ." "3" } } ; @@ -94,8 +94,8 @@ HELP: buffer-capacity { $description "Outputs the buffer's maximum capacity before growing." } { $examples { $example - "USING: io.buffers ;" - "100 buffer-capacity ." + "USING: destructors io.buffers prettyprint ;" + "100 [ buffer-capacity ] with-disposal ." "100" } } ; @@ -115,8 +115,8 @@ HELP: byte>buffer { $warning "This word will corrupt memory if the buffer is full." } { $examples { $example - "USING: io.buffers ;" - "100 237 over byte>buffer buffer-pop ." + "USING: destructors io.buffers kernel prettyprint ;" + "100 [ 237 over byte>buffer buffer-pop ] with-disposal ." "237" } } ; diff --git a/basis/io/files/windows/windows-docs.factor b/basis/io/files/windows/windows-docs.factor index d9b3e16a8b..099efaa07c 100644 --- a/basis/io/files/windows/windows-docs.factor +++ b/basis/io/files/windows/windows-docs.factor @@ -5,8 +5,8 @@ HELP: open-read { $values { "path" "a filesystem path" } { "win32-file" "a win32 file-handle" } } { $description "Opens a file for reading and returns a filehandle to it." } { $examples - { $example - "USING: io.files.windows ;" + { $unchecked-example + "USING: io.files.windows prettyprint ;" "\"resource:core/kernel/kernel.factor\" absolute-path open-read ." "T{ win32-file { handle ALIEN: 234 } { ptr 0 } }" } diff --git a/basis/io/launcher/launcher-docs.factor b/basis/io/launcher/launcher-docs.factor index 08d3f6b99d..f4681ed315 100644 --- a/basis/io/launcher/launcher-docs.factor +++ b/basis/io/launcher/launcher-docs.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2007, 2008 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: help.markup help.syntax quotations kernel io io.files -math calendar ; +USING: calendar help.markup help.syntax io io.files kernel literals math +quotations sequences ; IN: io.launcher ARTICLE: "io.launcher.command" "Specifying a command" @@ -101,9 +101,9 @@ HELP: current-process-handle { $description "Returns the handle of the current process." } { $examples { $example - "USING: io.launcher ;" - "current-process-handle ." - "6881" + "USING: io.launcher math prettyprint ;" + "current-process-handle number? ." + "t" } } ; @@ -117,16 +117,9 @@ HELP: run-process { $description "Launches a process. The object can either be a string, a sequence of strings or a " { $link process } ". See " { $link "io.launcher.descriptors" } " for details." } { $examples { $example - "USING: io.launcher ;" + "USING: io.launcher prettyprint ;" "\"pwd\" run-process ." - "/tmp" - "T{ process" - " { command \"pwd\" }" - " { environment H{ } }" - " { environment-mode +append-environment+ }" - " { group +same-group+ }" - " { status 0 }" - "}" + "T{ process\n { command \"pwd\" }\n { environment H{ } }\n { environment-mode +append-environment+ }\n { group +same-group+ }\n { status 0 }\n}" } } { $notes "The output value can be passed to " { $link wait-for-process } " to get an exit code." } ; @@ -150,20 +143,23 @@ HELP: try-process { $description "Launches a process and waits for it to complete. If it exits with a non-zero status code, throws a " { $link process-failed } " error." } { $examples { $example - "USING: continuations io.launcher ;" - "[ \"ls --invalid-flag\" try-process ] [ ] recover ." - "ls: unknown flag \"--invalid-flag\"" - "Try with ”ls --help” for more information." - "T{ process-failed" - " { process" - " T{ process" - " { command \"ls --invalid-flag\" }" - " { environment H{ } }" - " { environment-mode +append-environment+ }" - " { group +same-group+ }" - " { status 2 }" - " }" - "}" + "USING: continuations io.launcher prettyprint ;" + "[ \"i-dont-exist\" try-process ] [ ] recover ." + $[ + { + "T{ process-failed" + " { process" + " T{ process" + " { command \"i-dont-exist\" }" + " { environment H{ } }" + " { environment-mode +append-environment+ }" + " { group +same-group+ }" + " { status 255 }" + " }" + " }" + "}" + } "\n" join + ] } } ; @@ -176,6 +172,7 @@ HELP: kill-process { $example "USING: io.launcher ;" "\"cat\" run-detached kill-process" + "" } } ; @@ -229,8 +226,8 @@ HELP: with-process-reader } { $description "Launches a process and redirects its output via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." } { $examples - { $example - "USING: io.launcher ;" + { $unchecked-example + "USING: io.launcher prettyprint ;" "\"ls -dl /etc\" utf8 [ contents ] with-process-reader ." "\"drwxr-xr-x 213 root root 12288 mar 11 18:52 /etc\\n\"" } diff --git a/basis/io/timeouts/timeouts-docs.factor b/basis/io/timeouts/timeouts-docs.factor index cf7ba5167c..ce71b1c99b 100644 --- a/basis/io/timeouts/timeouts-docs.factor +++ b/basis/io/timeouts/timeouts-docs.factor @@ -9,8 +9,8 @@ HELP: set-timeout { $values { "dt/f" { $maybe duration } } { "obj" object } } { $contract "Sets an object's timeout." } { $examples "Waits five seconds for a process that sleeps for ten seconds:" - { $example - "USING: calendar io.launcher io.timeouts ;" + { $unchecked-example + "USING: calendar io.launcher io.timeouts kernel ;" "\"sleep 10\" >process 5 seconds over set-timeout run-process" "Process was killed as a result of a call to" "kill-process, or a timeout" diff --git a/basis/math/matrices/elimination/elimination-docs.factor b/basis/math/matrices/elimination/elimination-docs.factor index 4a3bcabac0..9ea3f607d6 100644 --- a/basis/math/matrices/elimination/elimination-docs.factor +++ b/basis/math/matrices/elimination/elimination-docs.factor @@ -3,12 +3,12 @@ USING: help.markup help.syntax math sequences ; IN: math.matrices.elimination HELP: inverse -{ $values { "matrix" sequence } { "matrix" sequence } } +{ $values { "matrix" sequence } } { $description "Computes the multiplicative inverse of a matrix. Assuming the matrix is invertible." } { $examples "A matrix multiplied by its inverse is the identity matrix." { $example - "USING: math.matrices math.matrices.elimination prettyprint ;" + "USING: kernel math.matrices math.matrices.elimination prettyprint ;" "{ { 3 4 } { 7 9 } } dup inverse m. 2 identity-matrix = ." "t" } diff --git a/basis/math/matrices/matrices-docs.factor b/basis/math/matrices/matrices-docs.factor index 3a1eb0a542..2242715c93 100644 --- a/basis/math/matrices/matrices-docs.factor +++ b/basis/math/matrices/matrices-docs.factor @@ -1,5 +1,4 @@ USING: help.markup help.syntax math sequences ; - IN: math.matrices HELP: zero-matrix @@ -15,7 +14,7 @@ HELP: identity-matrix { $description "Creates an identity matrix of size " { $snippet "n x n" } ", where the diagonal values are all ones." } ; HELP: m.v -{ $values { "m" sequence } { "v" sequence } { "v" sequence } } +{ $values { "m" sequence } { "v" sequence } } { $description "Computes the dot product between a matrix and a vector." } { $examples { $example @@ -26,7 +25,7 @@ HELP: m.v } ; HELP: m. -{ $values { "m" sequence } { "m" sequence } { "m" sequence } } +{ $values { "m" sequence } } { $description "Computes the dot product between two matrices, i.e multiplies them." } { $examples { $example @@ -37,7 +36,7 @@ HELP: m. } ; HELP: m+ -{ $values { "m" sequence } { "m" sequence } { "m" sequence } } +{ $values { "m" sequence } } { $description "Adds the matrices component-wise." } { $examples { $example @@ -48,7 +47,7 @@ HELP: m+ } ; HELP: m- -{ $values { "m" sequence } { "m" sequence } { "m" sequence } } +{ $values { "m" sequence } } { $description "Subtracts the matrices component-wise." } { $examples { $example diff --git a/basis/urls/urls-docs.factor b/basis/urls/urls-docs.factor index 71423a2361..46deab82b9 100644 --- a/basis/urls/urls-docs.factor +++ b/basis/urls/urls-docs.factor @@ -157,11 +157,9 @@ HELP: url-addr "T{ inet { host \"ftp.cdrom.com\" } { port 21 } }" } { $example - "USING: prettyprint urls ;" + "USING: io.sockets.secure prettyprint urls ;" "URL\" https://google.com/\" url-addr ." - "T{ secure" - "{ addrspec T{ inet { host \"google.com\" } { port 443 } } }" - "}" + "T{ secure\n { addrspec T{ inet { host \"google.com\" } { port 443 } } }\n}" } } ; diff --git a/basis/vocabs/files/files-docs.factor b/basis/vocabs/files/files-docs.factor index 0cf6880bec..60eb4a9009 100644 --- a/basis/vocabs/files/files-docs.factor +++ b/basis/vocabs/files/files-docs.factor @@ -1,4 +1,4 @@ -USING: help.markup help.syntax strings ; +USING: help.markup help.syntax literals sequences strings ; IN: vocabs.files HELP: vocab-tests-path @@ -18,13 +18,17 @@ HELP: vocab-files { $description "Outputs a sequence of files comprising this vocabulary, or " { $link f } " if the vocabulary does not have a directory on disk." } { $examples { $example - "USING: vocabs.files ; " + "USING: prettyprint vocabs.files ; " "\"alien.libraries\" vocab-files ." - "{" - " \"resource:basis/alien/libraries/libraries.factor\"" - " \"resource:basis/alien/libraries/libraries-docs.factor\"" - " \"resource:basis/alien/libraries/libraries-tests.factor\"" - "}" + $[ + { + "{" + " \"resource:basis/alien/libraries/libraries.factor\"" + " \"resource:basis/alien/libraries/libraries-docs.factor\"" + " \"resource:basis/alien/libraries/libraries-tests.factor\"" + "}" + } "\n" join + ] } } ; @@ -33,17 +37,22 @@ HELP: vocab-tests { $description "Outputs a sequence of pathnames where the unit tests for " { $snippet "vocab" } " are located." } { $examples { $example - "USING: vocabs.files ; " + "USING: prettyprint vocabs.files ; " "\"xml\" vocab-tests ." - "{" - " \"resource:basis/xml/tests/xmode-dtd.factor\"" - " \"resource:basis/xml/tests/test.factor\"" - " \"resource:basis/xml/tests/state-parser-tests.factor\"" - " \"resource:basis/xml/tests/soap.factor\"" - " \"resource:basis/xml/tests/templating.factor\"" - " \"resource:basis/xml/tests/encodings.factor\"" - " \"resource:basis/xml/tests/xmltest.factor\"" - " \"resource:basis/xml/tests/funny-dtd.factor\"" - "}" + $[ + { + "{" + " \"resource:basis/xml/tests/xmode-dtd.factor\"" + " \"resource:basis/xml/tests/test.factor\"" + " \"resource:basis/xml/tests/state-parser-tests.factor\"" + " \"resource:basis/xml/tests/soap.factor\"" + " \"resource:basis/xml/tests/templating.factor\"" + " \"resource:basis/xml/tests/encodings.factor\"" + " \"resource:basis/xml/tests/xmltest.factor\"" + " \"resource:basis/xml/tests/funny-dtd.factor\"" + " \"resource:basis/xml/tests/cdata.factor\"" + "}" + } "\n" join + ] } } ; diff --git a/core/io/files/files-docs.factor b/core/io/files/files-docs.factor index fe52d79cea..c6e7e801d2 100644 --- a/core/io/files/files-docs.factor +++ b/core/io/files/files-docs.factor @@ -81,9 +81,9 @@ HELP: file-lines { $description "Opens the file at the given path using the given encoding, and returns a list of the lines in that file." } { $examples { $example - "USING: io.files io.encodings.utf8 ;" + "USING: io.files io.encodings.utf8 prettyprint sequences ;" "\"resource:core/kernel/kernel.factor\" utf8 file-lines first ." - "! Copyright (C) 2004, 2009 Slava Pestov." + "\"! Copyright (C) 2004, 2009 Slava Pestov.\"" } } { $errors "Throws an error if the file cannot be opened for reading." } ; diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor index 60db385cac..4b72acc0f2 100644 --- a/core/sequences/sequences-docs.factor +++ b/core/sequences/sequences-docs.factor @@ -948,8 +948,9 @@ HELP: head? { $description "Tests if " { $snippet "seq" } " starts with " { $snippet "begin" } ". If " { $snippet "begin" } " is longer than " { $snippet "seq" } ", this word outputs " { $link f } "." } { $examples { $example - "root-cache get keys [ \"help.l\" head? ] filter ." - "{ \"help.lint.checks\" \"help.lint.private\" \"help.lint\" }" + "USING: prettyprint sequences ;" + "{ \"accept\" \"adept\" \"advance\" \"advice\" \"affect\" } [ \"ad\" head? ] filter ." + "{ \"adept\" \"advance\" \"advice\" }" } } ; diff --git a/core/source-files/errors/errors-docs.factor b/core/source-files/errors/errors-docs.factor index 31351480b6..17d0094d54 100644 --- a/core/source-files/errors/errors-docs.factor +++ b/core/source-files/errors/errors-docs.factor @@ -12,7 +12,7 @@ HELP: error-type-holder { { $slot "icon" } { "path to an icon image representing this error type." } } { { $slot "quot" } { "quotation that produces a list of all errors of this type." } } { { $slot "forget-quot" } { "a quotation that removes errors of this type for a given word." } } - { { $slot "fatal?" } { "whether the error is fatal or not. default " { $snippet t } "." } } + { { $slot "fatal?" } { "whether the error is fatal or not. default " { $link t } "." } } } } ; @@ -29,12 +29,14 @@ HELP: all-errors { $description "Lists all errors in the system." } ; HELP: error-file +{ $values { "error" "an error" } { "file" "a file path" } } { $description "File in which the error occurred." } ; HELP: { $values { "error" "an error." } { "definition" "an asset that contains the error." } - { "class" "a tuple class deriving " { $snippet source-file-error } "." } + { "class" "a tuple class deriving source-file-error." } + { "source-file-error" source-file-error } } -{ $description "Creates a new " { $snippet source-file-error } " instance." } ; +{ $description "Creates a new " { $link source-file-error } " instance." } ; diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index 4d08312cc7..55390ec0e1 100644 --- a/core/words/words-docs.factor +++ b/core/words/words-docs.factor @@ -1,5 +1,5 @@ USING: definitions help.markup help.syntax kernel parser -kernel.private vocabs classes quotations +kernel.private vocabs classes quotations sequences strings effects compiler.units ; IN: words @@ -347,13 +347,13 @@ HELP: deprecated? { $notes "Outputs " { $link f } " if the object is not a word." } ; HELP: subwords -{ $values { "word" word } } +{ $values { "word" word } { "seq" sequence } } { $description "Lists all specializations for the given word." } { $examples { $example - "USING: math.functions ;" - "clear \ sin subwords ." - "{ M\ object sin M\ complex sin M\ real sin M\ float sin }" + "USING: math.functions prettyprint words ;" + "\\ sin subwords ." + "{ M\\ object sin M\\ complex sin M\\ real sin M\\ float sin }" } } { $notes "Outputs " { $link f } " if the word isn't generic." } ;