Minor documentation updates: json, xml, serialize

diff --git a/basis/json/reader/reader-docs.factor b/basis/json/reader/reader-docs.factor
index ea4dcbf954e77bbad8664b803470e3d57f9436fb..4700423db5958da67cf779376702f0a8a8d0091f 100644 (file)
--- a/basis/json/reader/reader-docs.factor
+++ b/basis/json/reader/reader-docs.factor
@@ -3,6 +3,12 @@
 USING: help.markup help.syntax ;
 IN: json.reader
 
-HELP: json> "( string -- object )"
-{ $values { "string" "a string in JSON format" } { "object" "yhe object deserialized from the JSON string" } }
+HELP: json> ( string -- object )
+{ $values { "string" "a string in JSON format" } { "object" "a deserialized object" } }
 { $description "Deserializes the JSON formatted string into a Factor object. JSON objects are converted to Factor hashtables. All other JSON objects convert to their obvious Factor equivalents." } ;
+
+ARTICLE: "json.reader" "JSON reader"
+"The " { $vocab-link "json.reader" } " vocabulary defines a word for parsing strings in JSON format."
+{ $subsection json> } ;
+
+ABOUT: "json.reader"

diff --git a/basis/json/writer/writer-docs.factor b/basis/json/writer/writer-docs.factor
index 21aa8b2cb5d453405a870d2748b7e8bd2215f47e..8512d80384454f7ca0c0aa7384953fdd81c03c2e 100644 (file)
--- a/basis/json/writer/writer-docs.factor
+++ b/basis/json/writer/writer-docs.factor
@@ -3,13 +3,19 @@
 USING: help.markup help.syntax ;
 IN: json.writer
 
-HELP: >json "( obj -- string )"
+HELP: >json
 { $values { "obj" "an object" } { "string" "the object converted to JSON format" } }
 { $description "Serializes the object into a JSON formatted string." } 
 { $see-also json-print } ;
 
-HELP: json-print "( obj -- )"
+HELP: json-print
 { $values { "obj" "an object" } }
 { $description "Serializes the object into a JSON formatted string and outputs it to the standard output stream." } 
 { $see-also >json } ;
 
+ARTICLE: "json.writer" "JSON writer"
+"The " { $vocab-link "json.writer" } " vocabulary defines words for converting objects to JSON format."
+{ $subsection >json }
+{ $subsection json-print } ;
+
+ABOUT: "json.writer"

diff --git a/basis/serialize/serialize-docs.factor b/basis/serialize/serialize-docs.factor
index fc060d6b33ae751e9033d7d52a0c7f55ddc8f158..34922a5eae4f52b76d91efd791b9e90293757fe8 100644 (file)
--- a/basis/serialize/serialize-docs.factor
+++ b/basis/serialize/serialize-docs.factor
@@ -1,22 +1,34 @@
 ! Copyright (C) 2006 Chris Double.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: help.syntax help.markup ;
+USING: help.syntax help.markup byte-arrays io ;
 IN: serialize
 
 HELP: serialize
-{ $values { "obj" "object to serialize" } 
-}
-{ $description "Serializes the object to the current output stream. Object references within the structure being serialized are maintained." } 
-{ $examples 
-    { $example "USING: serialize io.encodings.binary io.streams.byte-array prettyprint ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" }
-}
-{ $see-also deserialize } ;
+{ $values { "obj" "object to serialize" } }
+{ $description "Serializes the object to " { $link output-stream } "." } ;
 
 HELP: deserialize
-{ $values { "obj" "deserialized object" } 
+{ $values { "obj" "deserialized object" } }
+{ $description "Deserializes an object by reading from " { $link input-stream } "." } ;
+
+HELP: object>bytes
+{ $values { "obj" "object to serialize" } { "bytes" byte-array }
 }
-{ $description "Deserializes an object by reading from the current input stream. Object references within the structure that was originally serialized are maintained." } 
-{ $examples 
-    { $example "USING: serialize io.encodings.binary io.streams.byte-array prettyprint ;" "binary [ { 1 2 } serialize ] with-byte-writer\n\nbinary [ deserialize ] with-byte-reader ." "{ 1 2 }" }
+{ $description "Serializes the object to a byte array." } ;
+
+HELP: bytes>object
+{ $values { "bytes" byte-array } { "obj" "deserialized object" } 
 }
-{ $see-also serialize } ;
+{ $description "Deserializes an object from a byte array." } ;
+
+ARTICLE: "serialize" "Binary object serialization"
+"The " { $vocab-link "serialize" } " vocabulary implements binary serialization for all Factor data types except for continuations. Unlike the prettyprinter, shared structure and circularity is preserved."
+$nl
+"Storing objects on streams:"
+{ $subsection serialize }
+{ $subsection deserialize }
+"Storing objects as byte arrays:"
+{ $subsection object>bytes }
+{ $subsection bytes>object } ;
+
+ABOUT: "serialize"

diff --git a/basis/serialize/serialize.factor b/basis/serialize/serialize.factor
index 52c1535886fe14dde59cc0e694da100db2a9dccf..2e72fa12cff058564bd79ae06ea43b4a724bdb91 100644 (file)
--- a/basis/serialize/serialize.factor
+++ b/basis/serialize/serialize.factor
@@ -15,6 +15,8 @@ locals prettyprint compiler.units sequences.private
 classes.tuple.private ;
 IN: serialize
 
+<PRIVATE
+
 ! Variable holding a assoc of objects already serialized
 SYMBOL: serialized
 
@@ -299,6 +301,8 @@ SYMBOL: deserialized
 : (deserialize) ( -- obj )
     deserialize* [ "End of stream" throw ] unless ;
 
+PRIVATE>
+
 : deserialize ( -- obj )
     ! [
     V{ } clone deserialized

diff --git a/basis/xml/xml-docs.factor b/basis/xml/xml-docs.factor
index 6a2ff1109ec67c8cc076dafa8ee7f15cac06a2af..248a43ed6347fed72fb2d7213ccf78d5cd6e674f 100644 (file)
--- a/basis/xml/xml-docs.factor
+++ b/basis/xml/xml-docs.factor
@@ -460,10 +460,8 @@ ARTICLE: { "xml" "entities" } "XML entities"
     { $subsection with-entities }\r
     { $subsection with-html-entities } ;\r
 \r
-ARTICLE: { "xml" "intro" } "XML"\r
-    "The XML module attempts to implement the XML 1.1 standard, converting strings of text into XML and vice versa. It currently is a work in progress."\r
-    $nl\r
-    "The XML module was implemented by Daniel Ehrenberg, with contributions from the Factor community"\r
+ARTICLE: "xml" "XML parser"\r
+"The " { $vocab-link "xml" } " vocabulary implements the XML 1.1 standard, converting strings of text into XML and vice versa."\r
     { $subsection { "xml" "reading" } }\r
     { $subsection { "xml" "writing" } }\r
     { $subsection { "xml" "classes" } }\r
@@ -476,4 +474,4 @@ ARTICLE: { "xml" "intro" } "XML"
 \r
 IN: xml\r
 \r
-ABOUT: { "xml" "intro" }\r
+ABOUT: "xml"\r