From 483325d0f06b2b545dfe4f2160a4ac4514c7d39a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Sat, 24 Jun 2017 16:42:59 +0200 Subject: [PATCH] core/: bunch of more docs --- core/classes/algebra/algebra-docs.factor | 26 ++++++++++++------- core/classes/classes-docs.factor | 4 +++ .../intersection/intersection-docs.factor | 2 +- core/compiler/units/units-docs.factor | 26 +++++++++++++------ core/definitions/definitions-docs.factor | 21 +++++++++++---- core/slots/slots-docs.factor | 17 ++++++++++++ core/syntax/syntax-docs.factor | 14 ++++++---- core/vocabs/loader/loader-docs.factor | 6 ++++- core/words/words-docs.factor | 22 +++++++++++++--- 9 files changed, 105 insertions(+), 33 deletions(-) diff --git a/core/classes/algebra/algebra-docs.factor b/core/classes/algebra/algebra-docs.factor index 01663ad116..747bbf6d0d 100644 --- a/core/classes/algebra/algebra-docs.factor +++ b/core/classes/algebra/algebra-docs.factor @@ -1,5 +1,5 @@ -USING: classes classes.private help.markup help.syntax kernel -math sequences ; +USING: classes classes.algebra.private classes.private help.markup +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 -{ $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." } ; +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: 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." } ; diff --git a/core/classes/classes-docs.factor b/core/classes/classes-docs.factor index 8b9fcc8ade..bc75d45f42 100644 --- a/core/classes/classes-docs.factor +++ b/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." } diff --git a/core/classes/intersection/intersection-docs.factor b/core/classes/intersection/intersection-docs.factor index 6efdbdb010..7b20621e4c 100644 --- a/core/classes/intersection/intersection-docs.factor +++ b/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:" diff --git a/core/compiler/units/units-docs.factor b/core/compiler/units/units-docs.factor index 8fb41c24a5..4dfbacdf9c 100644 --- a/core/compiler/units/units-docs.factor +++ b/core/compiler/units/units-docs.factor @@ -1,6 +1,6 @@ -USING: compiler.units.private definitions help.markup help.syntax kernel -kernel.private parser quotations sequences source-files stack-checker.errors -words ; +USING: classes.tuple.private compiler.units.private definitions +help.markup help.syntax kernel kernel.private parser quotations +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 } } diff --git a/core/definitions/definitions-docs.factor b/core/definitions/definitions-docs.factor index b609c26f72..2d39e38741 100644 --- a/core/definitions/definitions-docs.factor +++ b/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 } "." } ; diff --git a/core/slots/slots-docs.factor b/core/slots/slots-docs.factor index b172713154..1eb0d61b8a 100644 --- a/core/slots/slots-docs.factor +++ b/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 diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor index 0122df285c..30e1860794 100644 --- a/core/syntax/syntax-docs.factor +++ b/core/syntax/syntax-docs.factor @@ -1,8 +1,7 @@ -USING: arrays assocs classes.tuple combinators command-line -effects generic generic.math generic.single help.markup -help.syntax io.pathnames kernel math parser sequences -vocabs.loader vocabs.parser words words.alias words.constant -words.symbol ; +USING: arrays assocs classes.algebra.private classes.tuple combinators +command-line effects generic generic.math generic.single help.markup +help.syntax io.pathnames kernel math parser sequences vocabs.loader +vocabs.parser words words.alias words.constant 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 } } diff --git a/core/vocabs/loader/loader-docs.factor b/core/vocabs/loader/loader-docs.factor index 6d8bad2536..5b62ab58bc 100755 --- a/core/vocabs/loader/loader-docs.factor +++ b/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" } } diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index 996995a2d3..28579db470 100644 --- a/core/words/words-docs.factor +++ b/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: } "." } ;