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

basis/io/buffers/buffers-docs.factor

@@ -49,7 +49,7 @@ $nl
 
 HELP: <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
 { $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 <buffer> B{ 7 14 21 } over >buffer buffer-read ."
+    "USING: destructors io.buffers kernel prettyprint ;"
+    "5 100 <buffer> [ 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 <buffer> B{ 7 14 21 } over >buffer buffer-length ."
+    "USING: destructors io.buffers kernel prettyprint ;"
+    "100 <buffer> [ 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> buffer-capacity ."
+    "USING: destructors io.buffers prettyprint ;"
+    "100 <buffer> [ 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 <buffer> 237 over byte>buffer buffer-pop ."
+    "USING: destructors io.buffers kernel prettyprint ;"
+    "100 <buffer> [ 237 over byte>buffer buffer-pop ] with-disposal ."
     "237"
   }
 } ;

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 } }"
   }

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."
+    "USING: continuations io.launcher prettyprint ;"
+    "[ \"i-dont-exist\" try-process ] [ ] recover ."
+    $[
+        {
             "T{ process-failed"
             "    { process"
             "        T{ process"
-    "         { command \"ls --invalid-flag\" }"
+            "            { command \"i-dont-exist\" }"
             "            { environment H{ } }"
             "            { environment-mode +append-environment+ }"
             "            { group +same-group+ }"
-    "         { status 2 }"
+            "            { 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\""
   }

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"

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"
   }

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

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}"
     }
 } ;
 

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\""
             "}"
+        } "\n" join
+    ]
   }
 } ;
 
@@ -33,8 +37,10 @@ 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\""
@@ -44,6 +50,9 @@ HELP: vocab-tests
             "    \"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
+    ]
   }
 } ;

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." } ;

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\" }"
   }
 } ;
 

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: <definition-error>
 { $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." } ;

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." } ;