From 19a8a9ac9bb7391ad9147b0c2889b1c2b6997ce0 Mon Sep 17 00:00:00 2001 From: Slava Pestov 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." } ;