Minor documentation updates: json, xml, serialize

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"

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"

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"

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

basis/xml/xml-docs.factor

@@ -460,10 +460,8 @@ ARTICLE: { "xml" "entities" } "XML entities"
     { $subsection with-entities }
     { $subsection with-html-entities } ;
 
-ARTICLE: { "xml" "intro" } "XML"
-    "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."
-    $nl
-    "The XML module was implemented by Daniel Ehrenberg, with contributions from the Factor community"
+ARTICLE: "xml" "XML parser"
+"The " { $vocab-link "xml" } " vocabulary implements the XML 1.1 standard, converting strings of text into XML and vice versa."
     { $subsection { "xml" "reading" } }
     { $subsection { "xml" "writing" } }
     { $subsection { "xml" "classes" } }
@@ -476,4 +474,4 @@ ARTICLE: { "xml" "intro" } "XML"
 
 IN: xml
 
-ABOUT: { "xml" "intro" }
+ABOUT: "xml"