Docs: bunch of smaller documentation fixes for various vocabs

diff --git a/basis/cpu/architecture/architecture-docs.factor b/basis/cpu/architecture/architecture-docs.factor
index bcb70beea3153273eed260c92c1d91bcecf98146..eff0de7d7f7c231017a55ac32b53f8f993007e80 100644 (file)
--- a/basis/cpu/architecture/architecture-docs.factor
+++ b/basis/cpu/architecture/architecture-docs.factor
@@ -5,6 +5,16 @@ QUALIFIED: vm
 IN: cpu.architecture
 
 <<
+STRING: ex-%allot
+USING: cpu.architecture make ;
+[ RAX 40 tuple RCX %allot ] B{ } make disassemble
+0000000002270cc0: 498d4d10        lea rcx, [r13+0x10]
+0000000002270cc4: 488b01          mov rax, [rcx]
+0000000002270cc7: 48c7001c000000  mov qword [rax], 0x1c
+0000000002270cce: 4883c807        or rax, 0x7
+0000000002270cd2: 48830130        add qword [rcx], 0x30
+;
+
 STRING: ex-%box-alien
 USING: compiler.codegen compiler.codegen.relocation cpu.architecture make ;
 init-fixup init-relocation [ RAX RBX RCX %box-alien ] B{ } make disassemble
@@ -22,22 +32,18 @@ init-fixup init-relocation [ RAX RBX RCX %box-alien ] B{ } make disassemble
 000000e9fcc720dd: 4889581a              mov [rax+0x1a], rbx
 ;
 
-STRING: ex-%allot
-USING: cpu.architecture make ;
-[ RAX 40 tuple RCX %allot ] B{ } make disassemble
-0000000002270cc0: 498d4d10        lea rcx, [r13+0x10]
-0000000002270cc4: 488b01          mov rax, [rcx]
-0000000002270cc7: 48c7001c000000  mov qword [rax], 0x1c
-0000000002270cce: 4883c807        or rax, 0x7
-0000000002270cd2: 48830130        add qword [rcx], 0x30
-;
-
 STRING: ex-%context
 USING: cpu.architecture make ;
 [ EAX %context ] B{ } make disassemble
 00000000010f5ed0: 418b4500  mov eax, [r13]
 ;
 
+STRING: ex-%copy
+USING: cpu.architecture make ;
+RAX RBX int-rep [ %copy ] B{ } make disassemble
+000000000108a970: 4889d8  mov rax, rbx
+;
+
 STRING: ex-%safepoint
 USING: cpu.architecture make ;
 init-relocation [ %safepoint ] B{ } make disassemble
@@ -54,10 +60,16 @@ USING: cpu.architecture make ;
 0000000000e63ac0: 4c897818    mov [rax+0x18], r15
 ;
 
-STRING: ex-%copy
-USING: cpu.architecture make ;
-RAX RBX int-rep [ %copy ] B{ } make disassemble
-000000000108a970: 4889d8  mov rax, rbx
+STRING: ex-%write-barrier
+USING: cpu.architecture make tools.disassembler ;
+init-relocation [ RAX RBX 3 -14 RCX RDX %write-barrier ] B{ } make disassemble
+000000000143f960: 488d4cd80e            lea rcx, [rax+rbx*8+0xe]
+000000000143f965: 48c1e908              shr rcx, 0x8
+000000000143f969: 48ba0000000000000000  mov rdx, 0x0
+000000000143f973: 48c60411c0            mov byte [rcx+rdx], 0xc0
+000000000143f978: 48c1e90a              shr rcx, 0xa
+000000000143f97c: 48ba0000000000000000  mov rdx, 0x0
+000000000143f986: 48c60411c0            mov byte [rcx+rdx], 0xc0
 ;
 >>
 
@@ -92,13 +104,18 @@ HELP: param-regs
 { $values { "abi" "a calling convention symbol" } { "regs" assoc } }
 { $description "Retrieves the order in which machine registers are used for parameters for the given calling convention." } ;
 
-HELP: %load-immediate
-{ $values { "reg" "a register symbol" } { "val" "a value" } }
-{ $description "Emits code for loading an immediate value into a register. On " { $link x86 } ", if val is 0, then an " { $link XOR } " instruction is emitted instead of " { $link MOV } "." } ;
-
-HELP: %call
-{ $values { "word" word } }
-{ $description "Emits code for calling a Factor word." } ;
+HELP: %allot
+{ $values
+  { "dst" "destination register symbol" }
+  { "size" "number of bytes to allocate" }
+  { "class" "one of the built-in classes listed in " { $link type-numbers } }
+  { "temp" "temporary register symbol" }
+}
+{ $description "Emits machine code for allocating memory." }
+{ $examples
+  "In this example 40 bytes is allocated and a tagged pointer to the memory is put in " { $link RAX } ":"
+  { $unchecked-example $[ ex-%allot ] }
+} ;
 
 HELP: %box
 { $values
@@ -116,6 +133,10 @@ HELP: %box-alien
 { $examples { $unchecked-example $[ ex-%box-alien ] } }
 { $see-also ##box-alien %allot } ;
 
+HELP: %call
+{ $values { "word" word } }
+{ $description "Emits code for calling a Factor word." } ;
+
 HELP: %context
 { $values { "dst" "a register symbol" } }
 { $description "Emits machine code for putting a pointer to the context field of the " { $link vm } " in a register." }
@@ -126,6 +147,20 @@ HELP: %copy
 { $description "Emits code copying a value from a register, arbitrary memory location or " { $link spill-slot } " to a destination." }
 { $examples { $unchecked-example $[ ex-%copy ] } } ;
 
+HELP: %load-immediate
+{ $values { "reg" "a register symbol" } { "val" "a value" } }
+{ $description "Emits code for loading an immediate value into a register. On " { $link x86 } ", if val is 0, then an " { $link XOR } " instruction is emitted instead of " { $link MOV } " because the former is shorter." }
+{ $see-also ##load-tagged } ;
+
+HELP: %local-allot
+{ $values
+  { "dst" "destination register symbol" }
+  { "size" "number of bytes to allocate" }
+  { "align" "alignment" }
+  { "offset" "where to allocate the data, relative to the stack register" }
+}
+{ $description "Emits machine code for stack \"allocating\" a chunk of memory. No memory is really allocated and instead a pointer to it is just put in the destination register." } ;
+
 HELP: %safepoint
 { $description "Emits a safe point to the current code sequence being generated." }
 { $examples { $unchecked-example $[ ex-%safepoint ] } } ;
@@ -135,28 +170,17 @@ HELP: %save-context
 { $description "Emits machine code for saving pointers to the callstack, datastack and retainstack in the current context field struct." }
 { $examples { $unchecked-example $[ ex-%save-context ] } } ;
 
-
-HELP: %allot
+HELP: %write-barrier
 { $values
-  { "dst" "destination register symbol" }
-  { "size" "number of bytes to allocate" }
-  { "class" "one of the built-in classes listed in " { $link type-numbers } }
-  { "temp" "temporary register symbol" }
+  { "src" "a register symbol" }
+  { "slot" "a register symbol" }
+  { "scale" integer }
+  { "tag" integer }
+  { "temp1" "a register symbol" }
+  { "temp2" "a register symbol" }
 }
-{ $description "Emits machine code for allocating memory." }
-{ $examples
-  "In this example 40 bytes is allocated and a tagged pointer to the memory is put in " { $link RAX } ":"
-  { $unchecked-example $[ ex-%allot ] }
-} ;
-
-HELP: %local-allot
-{ $values
-  { "dst" "destination register symbol" }
-  { "size" "number of bytes to allocate" }
-  { "align" "alignment" }
-  { "offset" "where to allocate the data, relative to the stack register" }
-}
-{ $description "Emits machine code for stack \"allocating\" a chunk of memory. No memory is really allocated and instead a pointer to it is just put in the destination register." } ;
+{ $description "Generates code for the " { $link ##write-barrier } " instruction." }
+{ $examples { $unchecked-example $[ ex-%write-barrier ] } } ;
 
 HELP: test-instruction?
 { $values { "?" "a boolean" } }
@@ -210,6 +234,8 @@ $nl
 }
 "Control flow code emitters:"
 { $subsections %call %jump %jump-label %return }
+"Slot access:"
+{ $subsections %write-barrier }
 "Representation metadata:"
 { $subsections
   narrow-vector-rep

diff --git a/basis/cpu/x86/x86-docs.factor b/basis/cpu/x86/x86-docs.factor
index 9e904eac7a9ff6bf15a4e360d1b05cf08a397351..6f89aa8f3e1c6d6aaaaa97de5a0e010eb12b2e4f 100644 (file)
--- a/basis/cpu/x86/x86-docs.factor
+++ b/basis/cpu/x86/x86-docs.factor
@@ -1,4 +1,5 @@
-USING: help.markup help.syntax math ;
+USING: cpu.x86.assembler.operands.private help.markup help.syntax layouts
+math ;
 IN: cpu.x86
 
 HELP: stack-reg
@@ -30,6 +31,24 @@ HELP: (%inc)
   }
 } ;
 
+HELP: (%slot)
+{ $values
+  { "obj" "a register symbol" }
+  { "slot" "a register symbol" }
+  { "scale" "number of bits required to address all bytes in a " { $link cell } "." }
+  { "tag" integer }
+  { "op" indirect }
+}
+{ $description "Creates an indirect operand for addressing a slot in a container." }
+{ $examples
+  { $unchecked-example
+    "USING: cpu.x86 ;"
+    "[ RAX RBX 3 -14 (%slot) EDI MOV ] B{ } make disassemble"
+    "0000000001dd0990: 897cd80e  mov [rax+rbx*8+0xe], edi"
+  }
+} ;
+
+
 HELP: decr-stack-reg
 { $values { "n" number } }
 { $description "Emits an instruction for decrementing the stack register the given number of bytes." } ;

diff --git a/basis/tools/walker/walker-docs.factor b/basis/tools/walker/walker-docs.factor
index 94c1a7790d1dd92e843971c215984c41d4d10ac3..d47a858bf3afc5bf2aaec4828df12b6cb153b467 100644 (file)
--- a/basis/tools/walker/walker-docs.factor
+++ b/basis/tools/walker/walker-docs.factor
@@ -15,7 +15,7 @@ HELP: breakpoint-if
 { $description "Annotates a word definition to enter the single stepper if the quotation yields true. The quotation has access to the datastack as it exists just before " { $snippet "word" } " is called." }
 { $examples
     "Break if the input to sq is 3:"
-    { $unchecked-example 
+    { $unchecked-example
         "USE: tools.walker \\ sq [ dup 3 = ] breakpoint-if"
         ""
     }
@@ -27,6 +27,9 @@ HELP: B
 HELP: B:
 { $description "A breakpoint for parsing words. When this word is executed, it copies the definition of the following parsing word, prepends a " { $link break } " to it so that it is the first word to be executed when the definition is called, and calls this new definition.\n\nWhen the walker tool opens, execution will still be inside " { $link POSTPONE: B: } ". To step out of B: and into the parsing word, do just that: jump out with O, then into with I." } ;
 
+HELP: step-into
+{ $var-description "Signal set to the walker thread to step into the word." } ;
+
 ARTICLE: "breakpoints" "Setting breakpoints"
 "In addition to invoking the walker explicitly through the UI, it is possible to set breakpoints on words using words in the " { $vocab-link "tools.walker" } " vocabulary."
 $nl

diff --git a/core/bootstrap/primitives-docs.factor b/core/bootstrap/primitives-docs.factor
new file mode 100644 (file)
index 0000000..06d464d
--- /dev/null
+++ b/core/bootstrap/primitives-docs.factor
@@ -0,0 +1,7 @@
+USING: bootstrap.image.private effects help.markup help.syntax strings ;
+IN: bootstrap.primitives
+
+HELP: make-sub-primitive
+{ $values { "word" string } { "vocab" string } { "effect" effect } }
+{ $description "Defines a sub primitive word." }
+{ $see-also define-sub-primitive } ;

diff --git a/core/classes/classes-docs.factor b/core/classes/classes-docs.factor
index 29ac0dee4304d9ad292931a20a84ae2679f20d5d..54ba4883b668ea2d15770d30a01b7e93fd4ea447 100644 (file)
--- a/core/classes/classes-docs.factor
+++ b/core/classes/classes-docs.factor
@@ -84,6 +84,17 @@ HELP: classes
 HELP: update-map
 { $var-description "Assoc mapping each class to a set of classes defined in terms of this class. The " { $link define-class } " word uses this information to update generic words when classes are redefined." } ;
 
+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." }
+{ $examples
+  { $example
+    "USING: classes math prettyprint ;"
+    "fixnum predicate-def ."
+    "[ fixnum? ]"
+  }
+} ;
+
 HELP: predicate-word
 { $values { "word" word } { "predicate" "a predicate word" } }
 { $description "Suffixes the word's name with \"?\" and creates a word with that name in the same vocabulary as the word itself." } ;
@@ -165,4 +176,3 @@ HELP: forget-class
 HELP: forget-methods
 { $values { "class" class } }
 { $description "Forgets all methods defined on a class. In contrast to " { $link reset-class } ", this not only forgets accessors but also any methods at all on the class." } ;
-

diff --git a/core/continuations/continuations-docs.factor b/core/continuations/continuations-docs.factor
index d5bd657ae9037cb813fc75a33a22be533c6585ed..c86093507e81c10f9fff1a3a5525a0d38fe35967 100644 (file)
--- a/core/continuations/continuations-docs.factor
+++ b/core/continuations/continuations-docs.factor
@@ -116,13 +116,16 @@ HELP: catchstack
 { $values { "catchstack" "a vector of continuations" } }
 { $description "Outputs a copy of the current catchstack." } ;
 
+HELP: current-continuation
+{ $values { "continuation" continuation } }
+{ $description "Creates a continuation object from the current execution context." } ;
+
 HELP: set-catchstack
 { $values { "catchstack" "a vector of continuations" } }
 { $description "Replaces the catchstack with a copy of the given vector." } ;
 
 HELP: continuation
-{ $values { "continuation" continuation } }
-{ $description "Reifies the current continuation from the point immediately after which the caller returns." } ;
+{ $class-description "Reifies the current continuation from the point immediately after which the caller returns." } ;
 
 HELP: >continuation<
 { $values { "continuation" continuation } { "data" vector } { "call" vector } { "retain" vector } { "name" vector } { "catch" vector } }

diff --git a/core/definitions/definitions-docs.factor b/core/definitions/definitions-docs.factor
index d92c250faf34e9b9c2693b4ec6488a643a2e63b4..3da59b0e1c1ff261b6b7c577147643060d36e4b8 100644 (file)
--- a/core/definitions/definitions-docs.factor
+++ b/core/definitions/definitions-docs.factor
@@ -1,4 +1,4 @@
-USING: help.markup help.syntax words math source-files
+USING: generic hash-sets help.markup help.syntax words math source-files
 parser quotations compiler.units ;
 IN: definitions
 
@@ -91,3 +91,7 @@ HELP: forget-all
 { $values { "definitions" "a sequence of definition specifiers" } }
 { $description "Forgets every definition in a sequence." }
 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
+
+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 } ;

diff --git a/core/generic/parser/parser-docs.factor b/core/generic/parser/parser-docs.factor
new file mode 100644 (file)
index 0000000..ef56739
--- /dev/null
+++ b/core/generic/parser/parser-docs.factor
@@ -0,0 +1,10 @@
+USING: effects generic.single help.markup help.syntax math words ;
+IN: generic.parser
+
+HELP: generic-effect
+{ $values { "word" word } { "effect" effect } }
+{ $description "Gets the effect for a method." } ;
+
+ARTICLE: "generic.parser" "Utilities for generic word and method defining parsing words" "This vocab creates method words." ;
+
+ABOUT: "generic.parser"