finish io word docs

library/io/stream.factor

@@ -4,21 +4,14 @@ IN: io
 USING: errors hashtables generic kernel math namespaces
 sequences strings ;
 
-! Stream protocol.
 GENERIC: stream-close  ( stream -- )
 GENERIC: set-timeout   ( timeout stream -- )
-
-! Input stream protocol.
 GENERIC: stream-readln ( stream -- string )
 GENERIC: stream-read1  ( stream -- char/f )
 GENERIC: stream-read   ( count stream -- string )
-
-! Output stream protocol.
 GENERIC: stream-write1 ( char stream -- )
 GENERIC: stream-write  ( string stream -- )
 GENERIC: stream-flush  ( stream -- )
-
-! Extended output protocol.
 GENERIC: stream-terpri ( stream -- )
 GENERIC: stream-terpri* ( stream -- )
 GENERIC: stream-format ( string style stream -- )

library/io/stream.facts

@@ -8,7 +8,7 @@ $io-error ;
 
 HELP: set-timeout "( n stream -- )"
 { $values { "n" "an integer" } { "stream" "a stream" } }
-{ $contract "" } 
+{ $contract "Sets a timeout, in milliseconds, for closing the stream if there is no activity. Not all streams support timeouts." } 
 $io-error ;
 
 HELP: stream-readln "( stream -- str )"
@@ -54,12 +54,16 @@ $io-error ;
 
 HELP: stream-format "( str style stream -- )"
 { $values { "str" "a string" } { "style" "a hashtable" } { "stream" "an output stream" } }
-{ $contract "Writes formatted text to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output." }
+{ $contract "Writes formatted text to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output."
+$terpri
+"The " { $snippet "style" } " hashtable holds character style information. See " { $link "character-styles" } "." }
 $io-error ;
 
 HELP: with-nested-stream "( quot style stream -- )"
 { $values { "quot" "a quotation" } { "style" "a hashtable" } { "stream" "an output stream" } }
-{ $contract "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream, with formatting information applied." }
+{ $contract "Calls the quotation in a new dynamic scope with the " { $link stdio } " stream rebound to a nested paragraph stream, with formatting information applied."
+$terpri
+"The " { $snippet "style" } " hashtable holds paragraph style information. See " { $link "paragraph-styles" } "." }
 $io-error ;
 
 HELP: stream-print "( str stream -- )"
@@ -69,5 +73,5 @@ $io-error ;
 
 HELP: stream-copy "( in out -- )"
 { $values { "in" "an input stream" } { "out" "an output stream" } }
-{ $description "" } 
+{ $description "Copies the contents of one stream into another, closing both streams when done." } 
 $io-error ;

library/io/string-streams.facts

@@ -1,22 +1,23 @@
-USING: help io ;
+USING: help io strings ;
 
 HELP: <string-writer> "( -- stream )"
 { $values { "stream" "an output stream" } }
-{ $description "" } ;
+{ $description "Creates an output stream that collects text into a delegate string buffer. The contents of the buffer can be recovered by executing " { $link >string } ", and indeed all other sequence operations are permitted by virtue of the delegation." } ;
 
 HELP: string-out "( quot -- str )"
 { $values { "quot" "a quotation" } { "str" "a string" } }
-{ $description "" } ;
+{ $description "Calls the quotation in a new dynamic scope with " { $link stdio } " rebound to a new string writer. The accumulated string is output when the quotation returns." } ;
 
 HELP: <string-reader> "( str -- stream )"
 { $values { "str" "a string" } { "stream" "an input stream" } }
-{ $description "" } ;
+{ $description "Creates a new stream for reading " { $snippet "str" } " from beginning to end." }
+{ $notes "The implementation exploits the ability of string buffers to respond to the input stream protocol by reading characters from the end of the buffer." } ;
 
 HELP: string-in "( str quot -- )"
 { $values { "str" "a string" } { "quot" "a quotation" } }
-{ $description "" } ;
+{ $description "Calls the quotation in a new dynamic scope with " { $link stdio } " rebound to an input stream reading " { $snippet "str" } " from beginning to end. The accumulated string is output when the quotation returns." } ;
 
 HELP: contents "( stream -- str )"
 { $values { "stream" "an input stream" } { "str" "a string" } }
-{ $description "" }
+{ $description "Reads the contents of a stream into a string." }
 $io-error ;