vocabs.refresh: add a note about refesh-all after a fresh bootstrap

[factor.git] / basis / vocabs / refresh / refresh-docs.factor

diff --git a/basis/vocabs/refresh/refresh-docs.factor b/basis/vocabs/refresh/refresh-docs.factor
index 5652d2ac6a9d66e6e4b85a6d74b60971cf569e3c..f78664394da527935351ebec3919a5d0fc78f473 100644 (file)
--- a/basis/vocabs/refresh/refresh-docs.factor
+++ b/basis/vocabs/refresh/refresh-docs.factor
@@ -1,8 +1,8 @@
-USING: help.markup help.syntax strings ;
+USING: bootstrap.image help.markup help.syntax kernel strings ;
 IN: vocabs.refresh
 
 HELP: source-modified?
-{ $values { "path" "a pathname string" } { "?" "a boolean" } }
+{ $values { "path" "a pathname string" } { "?" boolean } }
 { $description "Tests if the source file has been modified since it was last loaded. This compares the file's CRC32 checksum of the file's contents against the previously-recorded value." } ;
 
 HELP: refresh
@@ -10,13 +10,23 @@ HELP: refresh
 { $description "Reloads source files and documentation belonging to loaded vocabularies whose names are prefixed by " { $snippet "prefix" } " which have been modified on disk." } ;
 
 HELP: refresh-all
-{ $description "Reloads source files and documentation for all loaded vocabularies which have been modified on disk." } ;
+{ $description "Reloads source files and documentation for all loaded vocabularies which have been modified on disk." }
+{ $notes
+"After a fresh bootstrap if " { $link refresh-all } " reloads any vocabularies, then the boot image was outdated. You can generate a new boot image with " { $link make-my-image } " and bootstrap again." } ;
 
 { refresh refresh-all } related-words
 
 ARTICLE: "vocabs.refresh" "Runtime code reloading"
-"Reloading source files changed on disk:"
-{ $subsection refresh }
-{ $subsection refresh-all } ;
+"The " { $vocab-link "vocabs.refresh" } " vocabulary implements automatic reloading of changed source files."
+$nl
+"With the help of the " { $vocab-link "io.monitors" } " vocabulary, loaded source files across all vocabulary roots are monitored for changes on disk."
+$nl
+"If a change to a source file is detected, the next invocation of " { $link refresh-all } " will compare the file's checksum against its previous value, reloading the file if necessary. This takes advantage of the fact that the " { $vocab-link "source-files" } " vocabulary records CRC32 checksums of source files that have been parsed by " { $link "parser" } "."
+$nl
+"Words for reloading source files:"
+{ $subsections
+    refresh
+    refresh-all
+} ;
 
 ABOUT: "vocabs.refresh"