hashtables.wrapped: add protocol documentation

diff --git a/core/hashtables/wrapped/wrapped-docs.factor b/core/hashtables/wrapped/wrapped-docs.factor
new file mode 100644 (file)
index 0000000..29ba6fe
--- /dev/null
+++ b/core/hashtables/wrapped/wrapped-docs.factor
@@ -0,0 +1,38 @@
+! Copyright (C)2023 Raghu Ranganathan.
+! See https://factorcode.org/license.txt for BSD license.
+USING: assocs help.markup help.syntax kernel ;
+IN: hashtables.wrapped
+
+HELP: wrap-key
+{ $values
+    { "key" object } { "wrapped-hash" object }
+    { "wrapped-key" object }
+}
+{ $description "" } ;
+
+HELP: wrapped-hashtable
+{ $class-description "" } ;
+
+ARTICLE: "hashtables.wrapped" "Wrapped Hashtable protocol"
+"The " { $vocab-link "hashtables.wrapped" } " describes a protocol for defining hashtables that "
+"use custom hashing algorithms."
+$nl
+"To create a custom wrapped hashtable, you must define a wrapper for your keys (usually a tuple class)."
+" For this wrapper, you have to define the following generics:"
+{ $list
+ { { $link hashcode* } " for your wrapper, which will contain the hashing algorithm you want to use. " }
+ { { $link wrap-key } " which is effectively a constructor for wrapping keys." }
+ { { $link equal? } " to check for equality of keys." }
+}
+
+"Other relevant generics are " { $link clone } " and " { $link new-assoc } "."
+$nl
+"Examples of wrapped hastable objects can be seen in:"
+{ $list 
+  { $vocab-link "hashtables.identity" }
+  { $vocab-link "hashtables.sequence" }
+  { $vocab-link "hashtables.numbers" }
+}
+;
+
+ABOUT: "hashtables.wrapped"