Docs: a few more examples for words that were missing them

diff --git a/basis/io/buffers/buffers-docs.factor b/basis/io/buffers/buffers-docs.factor
index 8a233337f0a23ff6bf6346eeed8a874b386ac118..c2bf6e0f67b9ae0154ccec620e3c7185f82cdfd7 100644 (file)
--- a/basis/io/buffers/buffers-docs.factor
+++ b/basis/io/buffers/buffers-docs.factor
@@ -69,19 +69,40 @@ HELP: buffer-end
 
 HELP: buffer-read
 { $values { "n" "a non-negative integer" } { "buffer" buffer } { "byte-array" byte-array } }
-{ $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
+  { $example
+    "USING: io.buffers ;"
+    "5 100 <buffer> B{ 7 14 21 } over >buffer buffer-read ."
+    "B{ 7 14 21 }"
+  }
+} ;
 
 HELP: buffer-length
 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
-{ $description "Outputs the number of unconsumed bytes in the buffer." } ;
+{ $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 ."
+    "3"
+  }
+} ;
 
 HELP: buffer-capacity
 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
-{ $description "Outputs the buffer's maximum capacity before growing." } ;
+{ $description "Outputs the buffer's maximum capacity before growing." }
+{ $examples
+  { $example
+    "USING: io.buffers ;"
+    "100 <buffer> buffer-capacity ."
+    "100"
+  }
+} ;
 
 HELP: buffer-empty?
 { $values { "buffer" buffer } { "?" "a boolean" } }
-{ $description "Tests if the buffer contains no more data to be read." } ;
+{ $description "Tests if the buffer contains no more data to be read or written." } ;
 
 HELP: >buffer
 { $values { "byte-array" byte-array } { "buffer" buffer } }
@@ -91,7 +112,14 @@ HELP: >buffer
 HELP: byte>buffer
 { $values { "byte" "a byte" } { "buffer" buffer } }
 { $description "Appends a single byte to a buffer." }
-{ $warning "This word will corrupt memory if the buffer is full." } ;
+{ $warning "This word will corrupt memory if the buffer is full." }
+{ $examples
+  { $example
+    "USING: io.buffers ;"
+    "100 <buffer> 237 over byte>buffer buffer-pop ."
+    "237"
+  }
+} ;
 
 HELP: n>buffer
 { $values { "n" "a non-negative integer" } { "buffer" buffer } }

diff --git a/basis/io/files/windows/windows-docs.factor b/basis/io/files/windows/windows-docs.factor
new file mode 100644 (file)
index 0000000..d9b3e16
--- /dev/null
+++ b/basis/io/files/windows/windows-docs.factor
@@ -0,0 +1,13 @@
+USING: help.markup help.syntax ;
+IN: io.files.windows
+
+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 ;"
+    "\"resource:core/kernel/kernel.factor\" absolute-path open-read ."
+    "T{ win32-file { handle ALIEN: 234 } { ptr 0 } }"
+  }
+} ;

diff --git a/basis/threads/threads-docs.factor b/basis/threads/threads-docs.factor
index 563a59dde9ea0316a9a52fce951938bc213e6243..b209626c0d23172cd4d20a93b86c763f53495482 100644 (file)
--- a/basis/threads/threads-docs.factor
+++ b/basis/threads/threads-docs.factor
@@ -95,7 +95,7 @@ HELP: run-queue
 { $values { "dlist" dlist } }
 { $var-description "Global variable holding the queue of runnable threads. Calls to " { $link yield } " switch to the thread which has been in the queue for the longest period of time."
 $nl
-"By convention, threads are queued with " { $link push-front } 
+"By convention, threads are queued with " { $link push-front }
 " and dequed with " { $link pop-back } "." } ;
 
 HELP: resume
@@ -154,7 +154,24 @@ $nl
      "The recommended way to pass data to the new thread is to explicitly construct a quotation containing the data, for example using " { $link curry } " or " { $link compose } "."
 }
 { $examples
+    "A simple thread that adds two numbers:"
     { $code "1 2 [ + . ] 2curry \"Addition thread\" spawn" }
+    "A thread that counts to 10:"
+    { $code
+      "USING: math.parser threads ;"
+      "[ 10 iota [ number>string write nl yield ] each ] \"test\" spawn"
+      "10 [ yield ] times"
+      "0"
+      "1"
+      "2"
+      "3"
+      "4"
+      "5"
+      "6"
+      "7"
+      "8"
+      "9"
+    }
 } ;
 
 HELP: spawn-server

diff --git a/core/io/files/files-docs.factor b/core/io/files/files-docs.factor
index 947e350bcd2103dcdc3335a2251437a215e2e6fe..fe52d79ceae2323e9efcd966b235b12a65e14374 100644 (file)
--- a/core/io/files/files-docs.factor
+++ b/core/io/files/files-docs.factor
@@ -79,6 +79,13 @@ HELP: set-file-lines
 HELP: file-lines
 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "seq" "an array of strings" } }
 { $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 ;"
+    "\"resource:core/kernel/kernel.factor\" utf8 file-lines first ."
+    "! Copyright (C) 2004, 2009 Slava Pestov."
+  }
+}
 { $errors "Throws an error if the file cannot be opened for reading." } ;
 
 HELP: set-file-contents