core/: bunch of more docs

core/classes/algebra/algebra-docs.factor

@@ -1,5 +1,5 @@
-USING: classes classes.private help.markup help.syntax kernel
+USING: classes classes.algebra.private classes.private help.markup
-math sequences ;
+help.syntax kernel math sequences ;
 IN: classes.algebra
 
 ARTICLE: "class-operations" "Class operations"
@@ -49,22 +49,30 @@ HELP: class<=
 { $description "Tests if all instances of " { $snippet "class1" } " are also instances of " { $snippet "class2" } "." }
 { $notes "Classes are partially ordered. This means that if " { $snippet "class1 <= class2" } " and " { $snippet "class2 <= class1" } ", then " { $snippet "class1 <= class2" } ". Also, if " { $snippet "class1 <= class2" } " and " { $snippet "class2 <= class3" } ", then " { $snippet "class1 <= class3" } "." } ;
 
-HELP: sort-classes
+HELP: class-and
-{ $values { "seq" "a sequence of class" } { "newseq" "a new sequence of classes" } }
+{ $values { "first" class } { "second" class } { "class" class } }
-{ $description "Outputs a linear sort of a sequence of classes. Larger classes come before their subclasses." } ;
+{ $description "Outputs the largest anonymous class contained in both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
+
+HELP: class-not
+{ $values { "class" class } { "complement" class } }
+{ $description "Outputs the complement class of 'class'." } ;
 
 HELP: class-or
 { $values { "first" class } { "second" class } { "class" class } }
 { $description "Outputs the smallest anonymous class containing both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
 
-HELP: class-and
-{ $values { "first" class } { "second" class } { "class" class } }
-{ $description "Outputs the largest anonymous class contained in both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
-
 HELP: classes-intersect?
 { $values { "first" class } { "second" class } { "?" boolean } }
 { $description "Tests if two classes have a non-empty intersection. If the intersection is empty, no object can be an instance of both classes at once." } ;
 
+HELP: normalize-class
+{ $values { "class" class } { "class'" class } }
+{ $description "Normalizes a class in such a way that it becomes easier to perform algebra on it." } ;
+
 HELP: smallest-class
 { $values { "classes" "a sequence of class words" } { "class/f" { $maybe class } } }
 { $description "Outputs a minimum class from the given sequence." } ;
+
+HELP: sort-classes
+{ $values { "seq" "a sequence of class" } { "newseq" "a new sequence of classes" } }
+{ $description "Outputs a linear sort of a sequence of classes. Larger classes come before their subclasses." } ;

core/classes/classes-docs.factor

@@ -100,6 +100,10 @@ HELP: define-predicate
 { $description "Defines a predicate word for a class." }
 $low-level-note ;
 
+HELP: metaclass-changed
+{ $values { "use" class } { "class" class } }
+{ $description "Notifies the class 'class' that its metaclass 'use' has changed." } ;
+
 HELP: predicate-def
 { $values { "obj" "a type object" } { "quot" quotation } }
 { $description "Outputs a quotation that can be used to check if objects are an instance of the given type." }

core/classes/intersection/intersection-docs.factor

@@ -4,7 +4,7 @@ layouts classes.private classes compiler.units ;
 IN: classes.intersection
 
 ARTICLE: "intersections" "Intersection classes"
-"An object is an instance of a intersection class if it is an instance of all of its participants."
+"An object is an instance of an intersection class if it is an instance of all of its participants."
 { $subsections POSTPONE: INTERSECTION: }
 { $subsections define-intersection-class }
 "Intersection classes can be introspected:"

core/compiler/units/units-docs.factor

@@ -1,6 +1,6 @@
-USING: compiler.units.private definitions help.markup help.syntax kernel
+USING: classes.tuple.private compiler.units.private definitions
-kernel.private parser quotations sequences source-files stack-checker.errors
+help.markup help.syntax kernel kernel.private parser quotations
-words ;
+sequences source-files stack-checker.errors words ;
 IN: compiler.units
 
 ARTICLE: "compilation-units-internals" "Compilation units internals"
@@ -18,7 +18,14 @@ $nl
 "A hook to be called at the end of the compilation unit. If the optimizing compiler is loaded, this compiles new words with the " { $link "compiler" } ":"
 { $subsections recompile }
 "Low-level compiler interface exported by the Factor VM:"
-{ $subsections modify-code-heap } ;
+{ $subsections modify-code-heap }
+"Variables maintaining state within a compilation unit."
+{ $subsections
+  changed-definitions
+  maybe-changed
+  outdated-generics
+  outdated-tuples
+} ;
 
 ARTICLE: "compilation-units" "Compilation units"
 "A " { $emphasis "compilation unit" } " scopes a group of related definitions. They are compiled and entered into the system in one atomic operation."
@@ -45,6 +52,12 @@ HELP: bump-effect-counter?
 { $values { "?" boolean } }
 { $description "Whether the " { $link REDEFINITION-COUNTER } " should be increased." } ;
 
+HELP: new-definitions
+{ $var-description "Stores a pair of sets where the members form the set of definitions which were defined so far by the current parsing of " { $link current-source-file } "." } ;
+
+HELP: forgotten-definitions
+{ $var-description "All definitions (words and vocabs) that have been forgotten in the current compilation unit." } ;
+
 HELP: old-definitions
 { $var-description "Stores a pair of sets where the members form the set of definitions which were defined by " { $link current-source-file } " the most recent time it was loaded." } ;
 
@@ -57,9 +70,6 @@ HELP: remember-definition
 { $values { "definition" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
 { $description "Saves the location of a definition and associates this definition with the current source file." } ;
 
-HELP: new-definitions
-{ $var-description "Stores a pair of sets where the members form the set of definitions which were defined so far by the current parsing of " { $link current-source-file } "." } ;
-
 HELP: with-compilation-unit
 { $values { "quot" quotation } }
 { $description "Calls a quotation in a new compilation unit. The quotation can define new words and classes, as well as forget words. When the quotation returns, any changed words are recompiled, and changes are applied atomically." }
@@ -80,7 +90,7 @@ HELP: recompile
 
 HELP: to-recompile
 { $values { "words" sequence } }
-{ $description "Sequence of words that will be recompiled by the compilation unit." } ;
+{ $description "Sequence of words that will be recompiled by the compilation unit. The non-optimizing compiler only recompiles words whose definitions has changed. But the optimizing compiler, which can perform optimizations such as inlining, recompiles words that depends on the changed words." } ;
 
 HELP: no-compilation-unit
 { $values { "word" word } }

core/definitions/definitions-docs.factor

@@ -73,14 +73,17 @@ $nl
 
 ABOUT: "definitions"
 
+HELP: changed-definition
+{ $values { "defspec" "definition" } }
+{ $description "Adds the definitio to the unit's " { $link changed-definitions } "." } ;
+
+HELP: changed-definitions
+{ $var-description "A set that contains all words and vocabs whose definitions have changed or are new. " }
+{ $see-also changed-definition } ;
+
 HELP: changed-effects
 { $var-description "A set that contains all words whose stack effects have changed in the compilation unit." } ;
 
-HELP: set-where
-{ $values { "loc" "a " { $snippet "{ path line# }" } " pair" } { "defspec" "a definition specifier" } }
-{ $description "Sets the definition's location." }
-{ $notes "This word is used by the parser." } ;
-
 HELP: forget
 { $values { "defspec" "a definition specifier" } }
 { $description "Forgets about a definition. For example, if it is a word, it will be removed from its vocabulary." }
@@ -91,10 +94,18 @@ HELP: forget-all
 { $description "Forgets every definition in a sequence." }
 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
 
+HELP: maybe-changed
+{ $var-description "The set of definitions that has maybe changed in the compilation unit. For example, if a union class is redefined it will be added to this set because it is possible but not certain that it has become different." } ;
+
 HELP: outdated-generics
 { $var-description "A " { $link hash-set } " where newly defined generic words are kept until they are being remade." }
 { $see-also remake-generic remake-generics } ;
 
+HELP: set-where
+{ $values { "loc" "a " { $snippet "{ path line# }" } " pair" } { "defspec" "a definition specifier" } }
+{ $description "Sets the definition's location." }
+{ $notes "This word is used by the parser." } ;
+
 HELP: where
 { $values { "defspec" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
 { $description "Outputs the location of a definition. If the location is not known, will output " { $link f } "." } ;

core/slots/slots-docs.factor

@@ -116,6 +116,23 @@ $nl
 
 ABOUT: "slots"
 
+HELP: bad-initial-value
+{ $error-description "Thrown by " { $link POSTPONE: TUPLE: } " if a slot has an impossible initial value. "
+  { $examples
+    { $unchecked-example
+      "TUPLE: a { b integer initial: \"invalid\" } ;"
+      "1: TUPLE: a { b integer initial: \"invalid\" } ;"
+      "                                              ^"
+      "Incompatible initial value"
+      "name          \"b\""
+      "initial-value \"invalid\""
+      "class         integer"
+      ""
+      "Type :help for debugging help."
+    }
+  }
+} ;
+
 HELP: slot-spec
 { $class-description "A slot specification. The " { $snippet "\"slots\"" } " word property of " { $link builtin-class } " and " { $link tuple-class } " instances holds sequences of slot specifications."
 $nl

core/syntax/syntax-docs.factor

@@ -1,8 +1,7 @@
-USING: arrays assocs classes.tuple combinators command-line
+USING: arrays assocs classes.algebra.private classes.tuple combinators
-effects generic generic.math generic.single help.markup
+command-line effects generic generic.math generic.single help.markup
-help.syntax io.pathnames kernel math parser sequences
+help.syntax io.pathnames kernel math parser sequences vocabs.loader
-vocabs.loader vocabs.parser words words.alias words.constant
+vocabs.parser words words.alias words.constant words.symbol ;
-words.symbol ;
 IN: syntax
 
 ARTICLE: "parser-algorithm" "Parser algorithm"
@@ -364,6 +363,11 @@ HELP: B{
 { $description "Marks the beginning of a literal byte array. Literal byte arrays are terminated by " { $link POSTPONE: } } "." }
 { $examples { $code "B{ 1 2 3 }" } } ;
 
+HELP: intersection{
+{ $syntax "intersection{ elements... }" }
+{ $values { "elements" "a list of classoids" } }
+{ $description "Marks the beginning of a literal " { $link anonymous-intersection } " class." } ;
+
 HELP: H{
 { $syntax "H{ { key value }... }" }
 { $values { "key" object } { "value" object } }

core/vocabs/loader/loader-docs.factor

@@ -86,7 +86,11 @@ HELP: vocab-roots
 HELP: add-vocab-root
 { $values { "root" "a pathname string" } }
 { $description "Adds a directory pathname to the list of vocabulary roots." }
-{ $see-also ".factor-roots" } ;
+{ $see-also ".factor-roots" add-vocab-root-hook } ;
+
+HELP: add-vocab-root-hook
+{ $var-description "A quotation that is run when a vocab root is added." }
+{ $see-also add-vocab-root } ;
 
 HELP: find-vocab-root
 { $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string" } }

core/words/words-docs.factor

@@ -174,10 +174,23 @@ $nl
     { { { $snippet "\"superclass\"" } ", " { $snippet "\"predicate-definition\"" } } { $link "predicates" } }
 
     { { $snippet "\"members\"" } { $link "unions" } { $link "maybes" } }
-
+    {
+        { $snippet "\"instances\"" }
+        { "Lists the instances of the mixin class and where they are defined - " { $link "mixins" } }
+    }
+    {
+        { $snippet "\"predicate\"" }
+        { "A quotation that tests if the top of the stack is an instance of this class - " { $link "class-predicates" } }
+    }
     { { $snippet "\"slots\"" } { $link "slots" } }
-
+    {
-    { { $snippet "\"predicate\"" } { "A quotation that tests if the top of the stack is an instance of this class - " { $link "class-predicates" } } }
+        {
+            { $snippet "\"superclass\"" } ", "
+            { $snippet "\"predicate-definition\"" }
+        }
+        { $link "predicates" }
+    }
+    { { $snippet "\"type\"" } { $link "builtin-classes" } }
 } ;
 
 ARTICLE: "word.private" "Word implementation details"
@@ -240,7 +253,8 @@ ABOUT: "words"
 
 HELP: changed-effect
 { $values { "word" word } }
-{ $description "Signals to the compilation unit that the word has changed. It causes all words that depend on it to be recompiled in response." } ;
+{ $description "Signals to the compilation unit that the effect of the word has changed. It causes all words that depend on it to be recompiled in response." }
+{ $see-also changed-effects } ;
 
 HELP: deferred
 { $class-description "The class of deferred words created by " { $link POSTPONE: DEFER: } "." } ;