Docs: bunch of smaller documentation fixes for various vocabs

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
+STRING: ex-%write-barrier
-USING: cpu.architecture make ;
+USING: cpu.architecture make tools.disassembler ;
-RAX RBX int-rep [ %copy ] B{ } make disassemble
+init-relocation [ RAX RBX 3 -14 RCX RDX %write-barrier ] B{ } make disassemble
-000000000108a970: 4889d8  mov rax, rbx
+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
+HELP: %allot
-{ $values { "reg" "a register symbol" } { "val" "a value" } }
+{ $values
-{ $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 } "." } ;
+  { "dst" "destination register symbol" }
-
+  { "size" "number of bytes to allocate" }
-HELP: %call
+  { "class" "one of the built-in classes listed in " { $link type-numbers } }
-{ $values { "word" word } }
+  { "temp" "temporary register symbol" }
-{ $description "Emits code for calling a Factor word." } ;
+}
+{ $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,28 +147,10 @@ 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: %safepoint
+HELP: %load-immediate
-{ $description "Emits a safe point to the current code sequence being generated." }
+{ $values { "reg" "a register symbol" } { "val" "a value" } }
-{ $examples { $unchecked-example $[ ex-%safepoint ] } } ;
+{ $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: %save-context
-{ $values { "temp1" "a register symbol" } { "temp2" "a register symbol" } }
-{ $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
-{ $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: %local-allot
 { $values
@@ -158,6 +161,27 @@ HELP: %local-allot
 }
 { $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 ] } } ;
+
+HELP: %save-context
+{ $values { "temp1" "a register symbol" } { "temp2" "a register symbol" } }
+{ $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: %write-barrier
+{ $values
+  { "src" "a register symbol" }
+  { "slot" "a register symbol" }
+  { "scale" integer }
+  { "tag" integer }
+  { "temp1" "a register symbol" }
+  { "temp2" "a register symbol" }
+}
+{ $description "Generates code for the " { $link ##write-barrier } " instruction." }
+{ $examples { $unchecked-example $[ ex-%write-barrier ] } } ;
+
 HELP: test-instruction?
 { $values { "?" "a boolean" } }
 { $description "Does the current architecture have a test instruction? Used on x86 to rewrite some " { $link CMP } " instructions to less expensive " { $link TEST } "s." } ;
@@ -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

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

basis/tools/walker/walker-docs.factor

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

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

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

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 } }
+{ $class-description "Reifies the current continuation from the point immediately after which the caller returns." } ;
-{ $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 } }

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

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"