From 74cb1acd17815ee709fe2716120ead4703b7353e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Sat, 5 Dec 2015 16:34:46 +0100 Subject: [PATCH] Docs: more docs for vocabs in core/ --- core/alien/alien-docs.factor | 4 ++ core/compiler/units/units-docs.factor | 15 +++-- core/definitions/definitions-docs.factor | 9 ++- core/io/encodings/encodings-docs.factor | 12 +++- core/kernel/kernel-docs.factor | 3 + core/words/words-docs.factor | 79 ++++++++++++++++++------ 6 files changed, 94 insertions(+), 28 deletions(-) diff --git a/core/alien/alien-docs.factor b/core/alien/alien-docs.factor index 29a3d0e35f..e0b507509c 100644 --- a/core/alien/alien-docs.factor +++ b/core/alien/alien-docs.factor @@ -3,6 +3,10 @@ alien.syntax byte-arrays cpu.x86 eval help.markup help.syntax io io.backend kernel math quotations sequences system ; IN: alien +HELP: callee-cleanup? +{ $values { "abi" abi } { "?" boolean } } +{ $description { $link t } " if the calling convention is callee cleanup." } ; + HELP: cdecl { $description "This symbol is passed as the " { $snippet "abi" } " argument to " { $link alien-indirect } ", " { $link alien-callback } ", " { $link alien-assembly } ", and " { $link add-library } " to indicate that the standard C calling convention should be used, where the caller cleans up the stack frame after calling the function. This symbol only has meaning on 32-bit x86 platforms." } ; diff --git a/core/compiler/units/units-docs.factor b/core/compiler/units/units-docs.factor index a6489153d4..48bce46529 100644 --- a/core/compiler/units/units-docs.factor +++ b/core/compiler/units/units-docs.factor @@ -1,5 +1,6 @@ -USING: definitions help.markup help.syntax kernel parser -quotations sequences source-files stack-checker.errors words ; +USING: 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" @@ -40,6 +41,13 @@ $nl ABOUT: "compilation-units" +HELP: bump-effect-counter? +{ $values { "?" boolean } } +{ $description "Whether the " { $link REDEFINITION-COUNTER } " should be increased." } ; + +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." } ; + HELP: redefine-error { $values { "definition" "a definition specifier" } } { $description "Throws a " { $link redefine-error } "." } @@ -49,9 +57,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: 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." } ; - 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 } "." } ; diff --git a/core/definitions/definitions-docs.factor b/core/definitions/definitions-docs.factor index 3da59b0e1c..dbf7c81ea9 100644 --- a/core/definitions/definitions-docs.factor +++ b/core/definitions/definitions-docs.factor @@ -73,9 +73,8 @@ $nl ABOUT: "definitions" -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 } "." } ; +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" } } @@ -95,3 +94,7 @@ HELP: forget-all 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: 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/io/encodings/encodings-docs.factor b/core/io/encodings/encodings-docs.factor index 503d42e528..8009775f53 100644 --- a/core/io/encodings/encodings-docs.factor +++ b/core/io/encodings/encodings-docs.factor @@ -1,4 +1,4 @@ -USING: help.markup help.syntax io quotations math ; +USING: help.markup help.syntax io quotations math sequences ; IN: io.encodings HELP: @@ -18,9 +18,17 @@ $low-level-note ; HELP: decode-char { $values { "stream" "an underlying input stream" } { "encoding" "An encoding descriptor tuple" } { "char/f" "a code point or " { $link f } } } -{ $contract "Reads a single code point from the underlying stream, interpreting it by the encoding. Returns " { $link f } " if the stream is reached." } +{ $contract "Reads a single code point from the underlying stream, interpreting it by the encoding. Returns " { $link f } " if the stream end is reached." } $low-level-note ; +HELP: decode-until +{ $values + { "seps" sequence } + { "stream" "an input stream" } + { "encoding" "an encoding descriptor" } +} +{ $description "Decodes characters from the stream until one of the separators are encountered." } ; + HELP: encode-char { $values { "char" "a character" } { "stream" "an underlying output stream" } diff --git a/core/kernel/kernel-docs.factor b/core/kernel/kernel-docs.factor index 9e4c794c36..e11660d00e 100644 --- a/core/kernel/kernel-docs.factor +++ b/core/kernel/kernel-docs.factor @@ -5,6 +5,9 @@ IN: kernel HELP: WIN-EXCEPTION-HANDLER { $description "This special object is an " { $link alien } " containing a pointer to the processes global exception handler. Only applicable on " { $link windows } "." } ; +HELP: OBJ-UNDEFINED +{ $description "Default definition for undefined words" } ; + HELP: eq? { $values { "obj1" object } { "obj2" object } { "?" boolean } } { $description "Tests if two references point at the same object." } ; diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index 4226e25a40..0ab0a1c8ab 100644 --- a/core/words/words-docs.factor +++ b/core/words/words-docs.factor @@ -91,24 +91,62 @@ ARTICLE: "word-props" "Word properties" $nl "The following are some of the properties used by the library:" { $table - { "Property" "Documentation" } - { { $snippet "\"parsing\"" } { $link "parsing-words" } } - - { { { $snippet "\"inline\"" } ", " { $snippet "\"foldable\"" } ", " { $snippet "flushable" } } { $link "declarations" } } - - { { $snippet "\"loc\"" } { "Location information - " { $link where } } } - - { { { $snippet "\"methods\"" } ", " { $snippet "\"combination\"" } } { "Set on generic words - " { $link "generic" } } } - - { { { $snippet "\"reading\"" } ", " { $snippet "\"writing\"" } } { "Set on slot accessor words - " { $link "slots" } } } - - { { $snippet "\"declared-effect\"" } { $link "effects" } } - - { { { $snippet "\"help\"" } ", " { $snippet "\"help-loc\"" } ", " { $snippet "\"help-parent\"" } } { "Where word help is stored - " { $link "writing-help" } } } - - { { $snippet "\"specializer\"" } { $link "hints" } } - - { { $snippet "\"predicating\"" } " Set on class predicates, stores the corresponding class word" } + { "Property" "Documentation" } + { + { $snippet "\"declared-effect\"" } { $link "effects" } + } + { + { + { $snippet "\"inline\"" } ", " + { $snippet "\"foldable\"" } ", " + { $snippet "flushable" } + } + { $link "declarations" } + } + { + { + { $snippet "\"help\"" } ", " + { $snippet "\"help-loc\"" } ", " + { $snippet "\"help-parent\"" } + } + { "Where word help is stored - " { $link "writing-help" } } + } + { + { $snippet "\"intrinsic\"" } + { "Quotation run by the compiler during cfg building to emit the word inline." } + } + { + { $snippet "\"loc\"" } + { "Location information - " { $link where } } + } + { + { { $snippet "\"methods\"" } ", " { $snippet "\"combination\"" } } + { "Set on generic words - " { $link "generic" } } + } + { + { + { $snippet "\"outputs\"" } ", " + { $snippet "\"input-classes\"" } ", " + { $snippet "\"default-output-classes\"" } + } + { "A bunch of metadata used during the value propagation step of the compilation to produce type-optimized code." } + } + { + { $snippet "\"parsing\"" } + { $link "parsing-words" } + } + { + { $snippet "\"predicating\"" } + " Set on class predicates, stores the corresponding class word" + } + { + { { $snippet "\"reading\"" } ", " { $snippet "\"writing\"" } } + { "Set on slot accessor words - " { $link "slots" } } + } + { + { $snippet "\"specializer\"" } + { $link "hints" } + } } "Properties which are defined for classes only:" { $table @@ -182,11 +220,16 @@ $nl "deferred" "declarations" "words.introspection" + "word-props" } { $see-also "vocabularies" "vocabs.loader" "definitions" "see" } ; 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." } ; + HELP: deferred { $class-description "The class of deferred words created by " { $link POSTPONE: DEFER: } "." } ;