Update docs

diff --git a/basis/delegate/delegate-docs.factor b/basis/delegate/delegate-docs.factor
index 0d8781ab8a1b190212da8120c9524ca0a2b05bc3..cd7e4049ff6d14eb7a3116f27e0f85a67e788c64 100644 (file)
--- a/basis/delegate/delegate-docs.factor
+++ b/basis/delegate/delegate-docs.factor
@@ -21,7 +21,7 @@ HELP: CONSULT:
 { $syntax "CONSULT: group class
     code ;" }
 { $values { "group" "a protocol, generic word or tuple class" } { "class" "a class" } { "code" "code to get the object to which the method should be forwarded" } }
-{ $description "Declares that objects of " { $snippet "class" } " will delegate the generic words contained in " { $snippet "group" } " to the object returned by executing " { $snippet "code" } " with the original object as an input. " { $snippet "CONSULT:" } " will overwrite any existing methods on " { $snippet "class" } " for the members of " { $snippet "group" } ", but new methods can be added after the " { $snippet "CONSULT:" } " to override the delegation." } ;
+{ $description "Declares that objects of " { $snippet "class" } " will delegate the generic words contained in " { $snippet "group" } " to the object returned by executing " { $snippet "code" } " with the original object as an input. " { $snippet "CONSULT:" } " will overwrite any existing methods on " { $snippet "class" } " for the members of " { $snippet "group" } ", but new methods can be added after the " { $snippet "CONSULT:" } " to override the delegation. Currently, this is only supported for " { $snippet "standard-combination" } " and " { $snippet "hook-combination" } " generics." } ;
 
 HELP: BROADCAST:
 { $syntax "BROADCAST: group class
@@ -63,6 +63,6 @@ $nl
     POSTPONE: CONSULT:
     define-consult
 }
-"Every tuple class has an associated protocol consisting of all of its slot accessor methods. The " { $vocab-link "delegate.protocols" } " vocabulary defines formal protocols for the various informal protocols used in the Factor core, such as " { $link "sequence-protocol" } ", " { $link "assocs-protocol" } " or " { $link "stream-protocol" } ;
+"Every tuple class has an associated protocol consisting of all of its slot accessor methods. The " { $vocab-link "delegate.protocols" } " vocabulary defines formal protocols for the various informal protocols used in the Factor core, such as " { $link "sequence-protocol" } ", " { $link "assocs-protocol" } " or " { $link "stream-protocol" } "." ;
 
 ABOUT: "delegate"

diff --git a/core/generic/generic-docs.factor b/core/generic/generic-docs.factor
index 152964d20bb9859ed827d326e39a12b6d9e065da..d31ded6bc38afe89199da9864bf21cb138f274b7 100644 (file)
--- a/core/generic/generic-docs.factor
+++ b/core/generic/generic-docs.factor
@@ -195,3 +195,10 @@ HELP: no-next-method
     }
     "This results in the method on " { $link integer } " being called, which then calls the method on " { $link number } ". The latter then calls " { $link POSTPONE: call-next-method } ", however there is no method less specific than the method on " { $link number } " and so an error is thrown."
 } ;
+
+HELP: make-consult-quot
+! { $values { "consultation" object } { "word" word } { "quot" quotation } { "combination" combination } }
+{ $contract "This generic produces the body quotation that will be used to actually effect a method consultation from the " { $vocab-link "delegate" } "vocabulary." }
+{ $notes "This is already implemented for " { $snippet "standard-combination" } " and " { $snippet "hook-combination" } ", and thus only needs to be specialized if you are implementing " { $snippet "CONSULT:" } " for a different kind of combination." }
+{ $heading "Reasoning" }
+"For standard method combinations, this calls the quotation to obtain the consulted object, and then executes the generic word, which naturally dispatches against the object on the stack. This is not sufficient for hook combinations, which must have the generic word executed with a variable bound to the result of the quotation. This generic is what allows for specializing the behavior of the methods that " { $snippet "CONSULT:" } "creates." ;