From d32b9f9c90d1e34ea1782af365b8c0e9349b2f06 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Mon, 22 Jun 2015 10:59:00 +0200
Subject: [PATCH] locals.parser: docs for with-lambda-scope and some random doc
 additions

---
 basis/locals/parser/parser-docs.factor | 27 ++++++++++++++++++++++++++
 core/parser/parser-docs.factor         |  4 ++--
 core/vocabs/loader/loader-docs.factor  |  4 ++--
 core/vocabs/parser/parser-docs.factor  | 13 ++++++++++++-
 4 files changed, 43 insertions(+), 5 deletions(-)
 create mode 100644 basis/locals/parser/parser-docs.factor

diff --git a/basis/locals/parser/parser-docs.factor b/basis/locals/parser/parser-docs.factor
new file mode 100644
index 0000000000..ccd413bcb3
--- /dev/null
+++ b/basis/locals/parser/parser-docs.factor
@@ -0,0 +1,27 @@
+USING: help.markup help.syntax locals locals.types quotations strings
+vocabs.parser ;
+IN: locals.parser
+
+HELP: in-lambda?
+{ $var-description { $link t } " if we're currently parsing a lambda with lexical variables." } ;
+
+HELP: parse-def
+{ $values
+  { "name/paren" string }
+  { "def" "a " { $link def } " or a " { $link multi-def } }
+}
+{ $description "Parses the lexical variable bindings following a " { $link \ :> } " token." } ;
+
+HELP: with-lambda-scope
+{ $values { "assoc" "local variables" } { "reader-quot" quotation } }
+{ $description "Runs the quotation in a lambda scope. That means changes the qutoation does to the " { $link manifest } " will not escape after the qutoation ends." } ;
+
+ARTICLE: "locals.parser" "Utility words used by locals parsing words"
+"Words for parsing local words."
+$nl
+"Words for parsing variable assignments:"
+{ $subsections parse-def parse-multi-def parse-single-def }
+"Parsers for word and method definitions:"
+{ $subsections (::) (M::) } ;
+
+ABOUT: "locals.parser"
diff --git a/core/parser/parser-docs.factor b/core/parser/parser-docs.factor
index a4820f53cd..1fed04bd7a 100644
--- a/core/parser/parser-docs.factor
+++ b/core/parser/parser-docs.factor
@@ -150,8 +150,8 @@ HELP: no-word
 
 HELP: parse-word
 { $values { "string" string } { "word" word } }
-{ $description "If " { $snippet "string" } " is a valid number literal, it is converted to a number, otherwise the current vocabulary search path is searched for a word named by the string." }
-{ $errors "Throws an error if the token does not name a word, and does not parse as a number." }
+{ $description "The current vocabulary search path is searched for all words named by the " { $snippet "string" } ". If no words matches, an error is thrown, if one word matches, and it is already loaded, that word is returned. Otherwise throws a restartable error to let the user choose which word to use." }
+{ $errors "Throws a " { $link no-word-error } " if the string doesn't name a word." }
 { $notes "This word is used to implement " { $link scan-word } "." } ;
 
 HELP: parse-datum
diff --git a/core/vocabs/loader/loader-docs.factor b/core/vocabs/loader/loader-docs.factor
index e4be81052f..520ee41945 100755
--- a/core/vocabs/loader/loader-docs.factor
+++ b/core/vocabs/loader/loader-docs.factor
@@ -92,7 +92,7 @@ HELP: find-vocab-root
 { $description "Searches for a vocabulary in the vocabulary roots." } ;
 
 HELP: no-vocab
-{ $values { "name" "a vocabulary name" } } 
+{ $values { "name" "a vocabulary name" } }
 { $description "Throws a " { $link no-vocab } "." }
 { $error-description "Thrown when a " { $link POSTPONE: USE: } " or " { $link POSTPONE: USING: } " form refers to a non-existent vocabulary." } ;
 
@@ -124,7 +124,7 @@ HELP: run
 
 HELP: vocab-source-path
 { $values { "vocab" "a vocabulary specifier" } { "path/f" { $maybe "a pathname string" } } }
-{ $description "Outputs a pathname where source code for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ;
+{ $description "Outputs a pathname where source code for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a known directory on disk." } ;
 
 HELP: vocab-docs-path
 { $values { "vocab" "a vocabulary specifier" } { "path/f" { $maybe "a pathname string" } } }
diff --git a/core/vocabs/parser/parser-docs.factor b/core/vocabs/parser/parser-docs.factor
index 95e1c81095..9e58c0f89d 100644
--- a/core/vocabs/parser/parser-docs.factor
+++ b/core/vocabs/parser/parser-docs.factor
@@ -1,4 +1,5 @@
-USING: help.markup help.syntax parser strings words assocs vocabs ;
+USING: assocs continuations help.markup help.syntax parser sequences strings
+words vocabs ;
 IN: vocabs.parser
 
 ARTICLE: "word-search-errors" "Word lookup errors"
@@ -99,6 +100,16 @@ HELP: <manifest>
 { $values { "manifest" manifest } }
 { $description "Creates a new manifest." } ;
 
+HELP: <no-word-error>
+{ $values
+  { "name" "name of the missing words" }
+  { "possibilities" sequence }
+  { "error" error }
+  { "restarts" sequence }
+}
+{ $description "Creates a no word error." } ;
+
+
 HELP: set-current-vocab
 { $values { "name" string } }
 { $description "Sets the current vocabulary where new words will be defined, creating the vocabulary first if it does not exist." }
-- 
2.34.1