add article for multiline, more docs

diff --git a/basis/multiline/multiline-docs.factor b/basis/multiline/multiline-docs.factor
index 0c0eb5e9dd34eedb728dbe912af37f05f41e25e3..4782571d4aa82e9cfe6fdd491a1154a031312bb7 100644 (file)
--- a/basis/multiline/multiline-docs.factor
+++ b/basis/multiline/multiline-docs.factor
@@ -9,14 +9,30 @@ HELP: <"
 { $syntax "<\" text \">" }
 { $description "This forms a multiline string literal ending in \">. Unlike the " { $link POSTPONE: STRING: } " form, you can end it in the middle of a line. This construct is non-nesting. In the example above, the string would be parsed as \"text\"." } ;
 
-{ POSTPONE: <" POSTPONE: STRING: } related-words
+HELP: /*
+{ $syntax "/* comment */" }
+{ $description "Provides C-like comments that can span multiple lines. One caveat is that " { $snippet "/*" } " and " { $snippet "*/" } " are still tokens and must not abut the comment text itself." }
+{ $example "USING: multiline ;"
+           "/* I think that I shall never see"
+           "   A poem lovely as a tree. */"
+           ""
+} ;
 
-HELP: parse-here
-{ $values { "str" "a string" } }
-{ $description "Parses a multiline string literal, as used by " { $link POSTPONE: STRING: } "." } ;
+{ POSTPONE: <" POSTPONE: STRING: } related-words
 
 HELP: parse-multiline-string
 { $values { "end-text" "a string delineating the end" } { "str" "the parsed string" } }
-{ $description "Parses a multiline string literal, as used by " { $link POSTPONE: <" } ". The end-text is the delimiter for the end." } ;
+{ $description "Parses the input stream until the " { $snippet "end-text" } " is reached and returns the parsed text as a string." }
+{ $notes "Used to implement " { $link POSTPONE: /* } " and " { $link POSTPONE: <" } "." } ;
+
+ARTICLE: "multiline" "Multiline"
+"Multiline strings:"
+{ $subsection POSTPONE: STRING: }
+{ $subsection POSTPONE: <" }
+"Multiline comments:"
+{ $subsection POSTPONE: /* }
+"Writing new multiline parsing words:"
+{ $subsection parse-multiline-string }
+;
 
-{ parse-here parse-multiline-string } related-words
+ABOUT: "multiline"

diff --git a/basis/multiline/multiline.factor b/basis/multiline/multiline.factor
index 67bcc55a06da1e1f1f2cd1f712ec2b129b0eaaa3..561af504c6c6e191d3ada3b6416e0b40af7b55c0 100755 (executable)
--- a/basis/multiline/multiline.factor
+++ b/basis/multiline/multiline.factor
@@ -4,6 +4,7 @@ USING: namespaces parser lexer kernel sequences words quotations math
 accessors ;
 IN: multiline
 
+<PRIVATE
 : next-line-text ( -- str )
     lexer get dup next-line line-text>> ;
 
@@ -13,6 +14,7 @@ IN: multiline
         [ drop lexer get next-line ]
         [ % "\n" % (parse-here) ] if
     ] [ ";" unexpected-eof ] if* ;
+PRIVATE>
 
 : parse-here ( -- str )
     [ (parse-here) ] "" make but-last
@@ -22,6 +24,7 @@ IN: multiline
     CREATE-WORD
     parse-here 1quotation define-inline ; parsing
 
+<PRIVATE
 : (parse-multiline-string) ( start-index end-text -- end-index )
     lexer get line-text>> [
         2dup start
@@ -30,6 +33,7 @@ IN: multiline
             lexer get next-line swap (parse-multiline-string)
         ] if*
     ] [ nip unexpected-eof ] if* ;
+PRIVATE>
 
 : parse-multiline-string ( end-text -- str )
     [