steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

core/: bunch of more docs

modern-harvey2
Björn Lindqvist 2017-06-24 16:42:59 +02:00
parent f2a8a79a1a
commit 483325d0f0
9 changed files with 105 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
core/classes/algebra/algebra-docs.factor
View File

@ -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." } ;

4
core/classes/classes-docs.factor
View File

@ -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." }

2
core/classes/intersection/intersection-docs.factor
View File

@ -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:"

26
core/compiler/units/units-docs.factor
View File

@ -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 } }

21
core/definitions/definitions-docs.factor
View File

@ -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 } "." } ;

17
core/slots/slots-docs.factor
View File

@ -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

14
core/syntax/syntax-docs.factor
View File

@ -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 } }

6
core/vocabs/loader/loader-docs.factor
View File

@ -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" } }

22
core/words/words-docs.factor
View File

@ -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: } "." } ;