From 19a8a9ac9bb7391ad9147b0c2889b1c2b6997ce0 Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@slava-pestovs-macbook-pro.local>
Date: Sun, 21 Dec 2008 14:29:12 -0600
Subject: [PATCH] Minor documentation updates

---
 basis/logging/parser/parser-docs.factor   |  2 +-
 basis/tools/profiler/profiler-docs.factor | 18 ++++++++++++------
 core/compiler/errors/errors-docs.factor   |  6 ++++--
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/basis/logging/parser/parser-docs.factor b/basis/logging/parser/parser-docs.factor
index 76c7ab6c90..7ab1ad3883 100644
--- a/basis/logging/parser/parser-docs.factor
+++ b/basis/logging/parser/parser-docs.factor
@@ -13,7 +13,7 @@ HELP: parse-log
 } ;
 
 ARTICLE: "logging.parser" "Log file parser"
-"The " { $vocab-link "logging.parser" } " vocabulary parses log files output by the " { $vocab-link "logging" } " vocabulary. It is used by " { $link "logging.analysis" } " and " { $link "logging.insomniac" } " to analyze logs."
+"The " { $vocab-link "logging.parser" } " vocabulary parses log files output by the " { $vocab-link "logging" } " vocabulary. It is used by " { $link "logging.analysis" } " and " { $vocab-link "logging.insomniac" } " to analyze logs."
 $nl
 "There is only one primary entry point:"
 { $subsection parse-log } ;
diff --git a/basis/tools/profiler/profiler-docs.factor b/basis/tools/profiler/profiler-docs.factor
index 69edf1a7e0..da9171cedf 100644
--- a/basis/tools/profiler/profiler-docs.factor
+++ b/basis/tools/profiler/profiler-docs.factor
@@ -2,14 +2,18 @@ USING: tools.profiler.private tools.time help.markup help.syntax
 quotations io strings words definitions ;
 IN: tools.profiler
 
-ARTICLE: "profiling" "Profiling code" 
-"The " { $vocab-link "tools.profiler" } " vocabulary implements a simple call counting profiler. The profiler is completely accurate with words and methods which are compiled with the non-optimizing compiler. Some optimizations performed by the optimizing compiler can inhibit accurate call counting, however:"
+ARTICLE: "profiler-limitations" "Profiler limitations"
+"Certain optimizations performed by the compiler can inhibit accurate call counting:"
 { $list
-    "The optimizing compiler open-codes certain primitives with inline machine code, and in some cases optimizes them out altogether; this includes stack shuffling operations, conditionals, and many object allocation operations."
-    { "Calls to " { $link POSTPONE: inline } " words are not counted.." }
+    "Calls to open-coded intrinsics are not counted. Certain words are open-coded as inline machine code, and in some cases optimized out altogether; this includes stack shuffling operations, conditionals, and many object allocation operations."
+    { "Calls to " { $link POSTPONE: inline } " words are not counted." }
     { "Calls to methods which were inlined as a result of type inference are not counted." }
     "Tail-recursive loops will only count the initial invocation of the word, not every tail call."
-}
+} ;
+
+ARTICLE: "profiling" "Profiling code" 
+"The " { $vocab-link "tools.profiler" } " vocabulary implements a simple call counting profiler."
+$nl
 "Quotations can be passed to a combinator which calls them with the profiler enabled:"
 { $subsection profile }
 "After a quotation has been profiled, call counts can be presented in various ways:"
@@ -17,7 +21,9 @@ ARTICLE: "profiling" "Profiling code"
 { $subsection vocab-profile. }
 { $subsection usage-profile. }
 { $subsection vocabs-profile. }
-{ $subsection method-profile. } ;
+{ $subsection method-profile. }
+{ $subsection "profiler-limitations" }
+{ $see-also "ui-profiler" } ;
 
 ABOUT: "profiling"
 
diff --git a/core/compiler/errors/errors-docs.factor b/core/compiler/errors/errors-docs.factor
index aa4f8e329d..f5ecf5add1 100644
--- a/core/compiler/errors/errors-docs.factor
+++ b/core/compiler/errors/errors-docs.factor
@@ -3,18 +3,20 @@ USING: help.markup help.syntax vocabs.loader words io
 quotations words.symbol ;
 
 ARTICLE: "compiler-errors" "Compiler warnings and errors"
-"The compiler saves various notifications in a global variable:"
+"The compiler saves " { $link "inference-errors" } " in a global variable:"
 { $subsection compiler-errors }
 "These notifications can be viewed later:"
 { $subsection :errors }
 { $subsection :warnings }
 { $subsection :linkage }
 "Words such as " { $link require } " use a combinator which counts errors and prints a report at the end:"
-{ $link with-compiler-errors } ;
+{ $subsection with-compiler-errors } ;
 
 HELP: compiler-errors
 { $var-description "Global variable holding an assoc mapping words to compiler errors. This variable is set by " { $link with-compiler-errors } "." } ;
 
+ABOUT: "compiler-errors"
+
 HELP: compiler-error
 { $values { "error" "an error" } { "word" word } }
 { $description "If inside a " { $link with-compiler-errors } ", saves the error for future persual via " { $link :errors } ", " { $link :warnings } " and " { $link :linkage } ". If not inside a " { $link with-compiler-errors } ", ignores the error." } ;