steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docs: fixed doc example errors triggered by help-lint and added with-disposal where applicable

db4
Björn Lindqvist 2014-04-14 01:26:43 +02:00 committed by John Benediktsson
parent a48567b8af
commit b72fa3ba0a
12 changed files with 90 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
basis/io/buffers/buffers-docs.factor
View File

@ -49,7 +49,7 @@ $nl
HELP: <buffer> HELP: <buffer>
{ $values { "n" "a non-negative integer" } { "buffer" buffer } } { $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 HELP: buffer-reset
{ $values { "n" "a non-negative integer" } { "buffer" buffer } } { $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." } { $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 { $examples
{ $example { $example
"USING: io.buffers ;" "USING: destructors io.buffers kernel prettyprint ;"
"5 100 <buffer> B{ 7 14 21 } over >buffer buffer-read ." "5 100 <buffer> [ B{ 7 14 21 } over >buffer buffer-read ] with-disposal ."
"B{ 7 14 21 }" "B{ 7 14 21 }"
} }
} ; } ;
@ -83,8 +83,8 @@ HELP: buffer-length
{ $description "Outputs the number of unconsumed bytes in the buffer." } { $description "Outputs the number of unconsumed bytes in the buffer." }
{ $examples { $examples
{ $example { $example
"USING: io.buffers ;" "USING: destructors io.buffers kernel prettyprint ;"
"100 <buffer> B{ 7 14 21 } over >buffer buffer-length ." "100 <buffer> [ B{ 7 14 21 } over >buffer buffer-length ] with-disposal ."
"3" "3"
} }
} ; } ;
@ -94,8 +94,8 @@ HELP: buffer-capacity
{ $description "Outputs the buffer's maximum capacity before growing." } { $description "Outputs the buffer's maximum capacity before growing." }
{ $examples { $examples
{ $example { $example
"USING: io.buffers ;" "USING: destructors io.buffers prettyprint ;"
"100 <buffer> buffer-capacity ." "100 <buffer> [ buffer-capacity ] with-disposal ."
"100" "100"
} }
} ; } ;
@ -115,8 +115,8 @@ HELP: byte>buffer
{ $warning "This word will corrupt memory if the buffer is full." } { $warning "This word will corrupt memory if the buffer is full." }
{ $examples { $examples
{ $example { $example
"USING: io.buffers ;" "USING: destructors io.buffers kernel prettyprint ;"
"100 <buffer> 237 over byte>buffer buffer-pop ." "100 <buffer> [ 237 over byte>buffer buffer-pop ] with-disposal ."
"237" "237"
} }
} ; } ;

4
basis/io/files/windows/windows-docs.factor
View File

@ -5,8 +5,8 @@ HELP: open-read
{ $values { "path" "a filesystem path" } { "win32-file" "a win32 file-handle" } } { $values { "path" "a filesystem path" } { "win32-file" "a win32 file-handle" } }
{ $description "Opens a file for reading and returns a filehandle to it." } { $description "Opens a file for reading and returns a filehandle to it." }
{ $examples { $examples
{ $example { $unchecked-example
"USING: io.files.windows ;" "USING: io.files.windows prettyprint ;"
"\"resource:core/kernel/kernel.factor\" absolute-path open-read ." "\"resource:core/kernel/kernel.factor\" absolute-path open-read ."
"T{ win32-file { handle ALIEN: 234 } { ptr 0 } }" "T{ win32-file { handle ALIEN: 234 } { ptr 0 } }"
} }

57
basis/io/launcher/launcher-docs.factor
View File

@ -1,7 +1,7 @@
! Copyright (C) 2007, 2008 Slava Pestov. ! Copyright (C) 2007, 2008 Slava Pestov.
! See http://factorcode.org/license.txt for BSD license. ! See http://factorcode.org/license.txt for BSD license.
USING: help.markup help.syntax quotations kernel io io.files USING: calendar help.markup help.syntax io io.files kernel literals math
math calendar ; quotations sequences ;
IN: io.launcher IN: io.launcher
ARTICLE: "io.launcher.command" "Specifying a command" ARTICLE: "io.launcher.command" "Specifying a command"
@ -101,9 +101,9 @@ HELP: current-process-handle
{ $description "Returns the handle of the current process." } { $description "Returns the handle of the current process." }
{ $examples { $examples
{ $example { $example
"USING: io.launcher ;" "USING: io.launcher math prettyprint ;"
"current-process-handle ." "current-process-handle number? ."
"6881" "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." } { $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 { $examples
{ $example { $example
"USING: io.launcher ;" "USING: io.launcher prettyprint ;"
"\"pwd\" run-process ." "\"pwd\" run-process ."
"/tmp" "T{ process\n { command \"pwd\" }\n { environment H{ } }\n { environment-mode +append-environment+ }\n { group +same-group+ }\n { status 0 }\n}"
"T{ process"
" { command \"pwd\" }"
" { environment H{ } }"
" { environment-mode +append-environment+ }"
" { group +same-group+ }"
" { status 0 }"
"}"
} }
} }
{ $notes "The output value can be passed to " { $link wait-for-process } " to get an exit code." } ; { $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." } { $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 { $examples
{ $example { $example
"USING: continuations io.launcher ;" "USING: continuations io.launcher prettyprint ;"
"[ \"ls --invalid-flag\" try-process ] [ ] recover ." "[ \"i-dont-exist\" try-process ] [ ] recover ."
"ls: unknown flag \"--invalid-flag\"" $[
"Try with ”ls --help” for more information." {
"T{ process-failed" "T{ process-failed"
" { process" " { process"
" T{ process" " T{ process"
" { command \"ls --invalid-flag\" }" " { command \"i-dont-exist\" }"
" { environment H{ } }" " { environment H{ } }"
" { environment-mode +append-environment+ }" " { environment-mode +append-environment+ }"
" { group +same-group+ }" " { group +same-group+ }"
" { status 2 }" " { status 255 }"
" }" " }"
"}" " }"
"}"
} "\n" join
]
} }
} ; } ;
@ -176,6 +172,7 @@ HELP: kill-process
{ $example { $example
"USING: io.launcher ;" "USING: io.launcher ;"
"\"cat\" run-detached kill-process" "\"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." } { $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 { $examples
{ $example { $unchecked-example
"USING: io.launcher ;" "USING: io.launcher prettyprint ;"
"\"ls -dl /etc\" utf8 [ contents ] with-process-reader ." "\"ls -dl /etc\" utf8 [ contents ] with-process-reader ."
"\"drwxr-xr-x 213 root root 12288 mar 11 18:52 /etc\\n\"" "\"drwxr-xr-x 213 root root 12288 mar 11 18:52 /etc\\n\""
} }

4
basis/io/timeouts/timeouts-docs.factor
View File

@ -9,8 +9,8 @@ HELP: set-timeout
{ $values { "dt/f" { $maybe duration } } { "obj" object } } { $values { "dt/f" { $maybe duration } } { "obj" object } }
{ $contract "Sets an object's timeout." } { $contract "Sets an object's timeout." }
{ $examples "Waits five seconds for a process that sleeps for ten seconds:" { $examples "Waits five seconds for a process that sleeps for ten seconds:"
{ $example { $unchecked-example
"USING: calendar io.launcher io.timeouts ;" "USING: calendar io.launcher io.timeouts kernel ;"
"\"sleep 10\" >process 5 seconds over set-timeout run-process" "\"sleep 10\" >process 5 seconds over set-timeout run-process"
"Process was killed as a result of a call to" "Process was killed as a result of a call to"
"kill-process, or a timeout" "kill-process, or a timeout"

4
basis/math/matrices/elimination/elimination-docs.factor
View File

@ -3,12 +3,12 @@ USING: help.markup help.syntax math sequences ;
IN: math.matrices.elimination IN: math.matrices.elimination
HELP: inverse HELP: inverse
{ $values { "matrix" sequence } { "matrix" sequence } } { $values { "matrix" sequence } }
{ $description "Computes the multiplicative inverse of a matrix. Assuming the matrix is invertible." } { $description "Computes the multiplicative inverse of a matrix. Assuming the matrix is invertible." }
{ $examples { $examples
"A matrix multiplied by its inverse is the identity matrix." "A matrix multiplied by its inverse is the identity matrix."
{ $example { $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 = ." "{ { 3 4 } { 7 9 } } dup inverse m. 2 identity-matrix = ."
"t" "t"
} }

9
basis/math/matrices/matrices-docs.factor
View File

@ -1,5 +1,4 @@
USING: help.markup help.syntax math sequences ; USING: help.markup help.syntax math sequences ;
IN: math.matrices IN: math.matrices
HELP: zero-matrix 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." } ; { $description "Creates an identity matrix of size " { $snippet "n x n" } ", where the diagonal values are all ones." } ;
HELP: m.v 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." } { $description "Computes the dot product between a matrix and a vector." }
{ $examples { $examples
{ $example { $example
@ -26,7 +25,7 @@ HELP: m.v
} ; } ;
HELP: m. HELP: m.
{ $values { "m" sequence } { "m" sequence } { "m" sequence } } { $values { "m" sequence } }
{ $description "Computes the dot product between two matrices, i.e multiplies them." } { $description "Computes the dot product between two matrices, i.e multiplies them." }
{ $examples { $examples
{ $example { $example
@ -37,7 +36,7 @@ HELP: m.
} ; } ;
HELP: m+ HELP: m+
{ $values { "m" sequence } { "m" sequence } { "m" sequence } } { $values { "m" sequence } }
{ $description "Adds the matrices component-wise." } { $description "Adds the matrices component-wise." }
{ $examples { $examples
{ $example { $example
@ -48,7 +47,7 @@ HELP: m+
} ; } ;
HELP: m- HELP: m-
{ $values { "m" sequence } { "m" sequence } { "m" sequence } } { $values { "m" sequence } }
{ $description "Subtracts the matrices component-wise." } { $description "Subtracts the matrices component-wise." }
{ $examples { $examples
{ $example { $example

6
basis/urls/urls-docs.factor
View File

@ -157,11 +157,9 @@ HELP: url-addr
"T{ inet { host \"ftp.cdrom.com\" } { port 21 } }" "T{ inet { host \"ftp.cdrom.com\" } { port 21 } }"
} }
{ $example { $example
"USING: prettyprint urls ;" "USING: io.sockets.secure prettyprint urls ;"
"URL\" https://google.com/\" url-addr ." "URL\" https://google.com/\" url-addr ."
"T{ secure" "T{ secure\n { addrspec T{ inet { host \"google.com\" } { port 443 } } }\n}"
"{ addrspec T{ inet { host \"google.com\" } { port 443 } } }"
"}"
} }
} ; } ;

45
basis/vocabs/files/files-docs.factor
View File

@ -1,4 +1,4 @@
USING: help.markup help.syntax strings ; USING: help.markup help.syntax literals sequences strings ;
IN: vocabs.files IN: vocabs.files
HELP: vocab-tests-path 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." } { $description "Outputs a sequence of files comprising this vocabulary, or " { $link f } " if the vocabulary does not have a directory on disk." }
{ $examples { $examples
{ $example { $example
"USING: vocabs.files ; " "USING: prettyprint vocabs.files ; "
"\"alien.libraries\" vocab-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." } { $description "Outputs a sequence of pathnames where the unit tests for " { $snippet "vocab" } " are located." }
{ $examples { $examples
{ $example { $example
"USING: vocabs.files ; " "USING: prettyprint vocabs.files ; "
"\"xml\" vocab-tests ." "\"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/xmode-dtd.factor\""
" \"resource:basis/xml/tests/soap.factor\"" " \"resource:basis/xml/tests/test.factor\""
" \"resource:basis/xml/tests/templating.factor\"" " \"resource:basis/xml/tests/state-parser-tests.factor\""
" \"resource:basis/xml/tests/encodings.factor\"" " \"resource:basis/xml/tests/soap.factor\""
" \"resource:basis/xml/tests/xmltest.factor\"" " \"resource:basis/xml/tests/templating.factor\""
" \"resource:basis/xml/tests/funny-dtd.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
]
} }
} ; } ;

4
core/io/files/files-docs.factor
View File

@ -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." } { $description "Opens the file at the given path using the given encoding, and returns a list of the lines in that file." }
{ $examples { $examples
{ $example { $example
"USING: io.files io.encodings.utf8 ;" "USING: io.files io.encodings.utf8 prettyprint sequences ;"
"\"resource:core/kernel/kernel.factor\" utf8 file-lines first ." "\"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." } ; { $errors "Throws an error if the file cannot be opened for reading." } ;

5
core/sequences/sequences-docs.factor
View File

@ -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 } "." } { $description "Tests if " { $snippet "seq" } " starts with " { $snippet "begin" } ". If " { $snippet "begin" } " is longer than " { $snippet "seq" } ", this word outputs " { $link f } "." }
{ $examples { $examples
{ $example { $example
"root-cache get keys [ \"help.l\" head? ] filter ." "USING: prettyprint sequences ;"
"{ \"help.lint.checks\" \"help.lint.private\" \"help.lint\" }" "{ \"accept\" \"adept\" \"advance\" \"advice\" \"affect\" } [ \"ad\" head? ] filter ."
"{ \"adept\" \"advance\" \"advice\" }"
} }
} ; } ;

8
core/source-files/errors/errors-docs.factor
View File

@ -12,7 +12,7 @@ HELP: error-type-holder
{ { $slot "icon" } { "path to an icon image representing this error type." } } { { $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 "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 "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." } ; { $description "Lists all errors in the system." } ;
HELP: error-file HELP: error-file
{ $values { "error" "an error" } { "file" "a file path" } }
{ $description "File in which the error occurred." } ; { $description "File in which the error occurred." } ;
HELP: <definition-error> HELP: <definition-error>
{ $values { $values
{ "error" "an error." } { "error" "an error." }
{ "definition" "an asset that contains the 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." } ;

10
core/words/words-docs.factor
View File

@ -1,5 +1,5 @@
USING: definitions help.markup help.syntax kernel parser USING: definitions help.markup help.syntax kernel parser
kernel.private vocabs classes quotations kernel.private vocabs classes quotations sequences
strings effects compiler.units ; strings effects compiler.units ;
IN: words IN: words
@ -347,13 +347,13 @@ HELP: deprecated?
{ $notes "Outputs " { $link f } " if the object is not a word." } ; { $notes "Outputs " { $link f } " if the object is not a word." } ;
HELP: subwords HELP: subwords
{ $values { "word" word } } { $values { "word" word } { "seq" sequence } }
{ $description "Lists all specializations for the given word." } { $description "Lists all specializations for the given word." }
{ $examples { $examples
{ $example { $example
"USING: math.functions ;" "USING: math.functions prettyprint words ;"
"clear \ sin subwords ." "\\ sin subwords ."
"{ M\ object sin M\ complex sin M\ real sin M\ float sin }" "{ M\\ object sin M\\ complex sin M\\ real sin M\\ float sin }"
} }
} }
{ $notes "Outputs " { $link f } " if the word isn't generic." } ; { $notes "Outputs " { $link f } " if the word isn't generic." } ;