From 712d6bf1c87e1877953e5e832cc4d5f22379a4c9 Mon Sep 17 00:00:00 2001
From: Jon Harper <jon.harper87@gmail.com>
Date: Wed, 21 May 2014 22:54:46 +0200
Subject: [PATCH] YAML: better docs for >yaml, typos

---
 extra/yaml/yaml-docs.factor | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/extra/yaml/yaml-docs.factor b/extra/yaml/yaml-docs.factor
index dbe7c7c9a3..978fd5d1a7 100644
--- a/extra/yaml/yaml-docs.factor
+++ b/extra/yaml/yaml-docs.factor
@@ -17,21 +17,31 @@ HELP: >yaml-docs
     { "seq" sequence }
     { "str" string }
 }
-{ $description "Serializes the sequence into a YAML formatted string. Each element is outputted as a YAML document" } ;
+{ $description "Serializes the sequence into a YAML formatted string. Each element is outputted as a YAML document." } ;
 
 HELP: yaml-docs>
 { $values
     { "str" string }
     { "arr" array }
 }
-{ $description "Deserializes the YAML formatted string into a Factor array. Each document becomes an element of the array" } ;
+{ $description "Deserializes the YAML formatted string into a Factor array. Each document becomes an element of the array." } ;
 
 HELP: yaml>
 { $values
     { "str" string }
     { "obj" object }
 }
-{ $description "Deserializes the YAML formatted string into a Factor object." } ;
+{ $description "Deserializes the YAML formatted string into a Factor object. Throws "
+{ $link yaml-no-document } " when there is no document (for example the empty string)."
+$nl
+}
+{ $notes
+"Contrary to " { $link yaml-docs> } ", this word only parses the input until one document is produced."
+" Valid or invalid content after the first document is ignored."
+" To verifiy that the whole input is one valid YAML document, use "
+{ $link yaml-docs> } " and assert that the length of the output array is 1."
+}
+;
 
 HELP: libyaml-emitter-error
 { $values