classes.maybe-docs: create some documentation for the maybe vocab

Integrate the pointers to the new article into existing help system,
primarily by looking for the uses of the "unions" article.

diff --git a/core/classes/classes-docs.factor b/core/classes/classes-docs.factor
index 0ee96e1ead6c4431c352b69f6653127f53ee41dc..8b9fcc8ade0eb8055e61d6503ae319dd0a43a1df 100644 (file)
--- a/core/classes/classes-docs.factor
+++ b/core/classes/classes-docs.factor
@@ -54,6 +54,7 @@ $nl
     "builtin-classes"
     "unions"
     "intersections"
+    "maybes"
     "mixins"
     "predicates"
     "singletons"

diff --git a/core/classes/maybe/maybe-docs.factor b/core/classes/maybe/maybe-docs.factor
new file mode 100644 (file)
index 0000000..ca1d2ca
--- /dev/null
+++ b/core/classes/maybe/maybe-docs.factor
@@ -0,0 +1,19 @@
+! Copyright (C) 2017 Alexander Ilin.
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax kernel ;
+IN: classes.maybe
+
+ABOUT: "maybes"
+
+ARTICLE: "maybes" "Maybe classes"
+"A " { $snippet "maybe" } " is an anonymous union class (" { $link "unions" } ") of its members and the " { $link POSTPONE: f } " class. An object is an instance of a " { $snippet "maybe" } " class if it is either an instance of any of its participants, or " { $link POSTPONE: f } "." $nl
+"The " { $snippet "maybe" } " classes are used to declare typed slots that are optional for a tuple. Without this mechanism it would be an error to assign " { $link POSTPONE: f } " to such a typed slot, and therefore any tuple containing them without specifying an " { $link POSTPONE: initial: } " value could not be created with the word " { $link new } "." $nl
+"A slot with an empty " { $snippet "maybe{ }" } " class can only hold the " { $link POSTPONE: f } " value."
+{ $examples
+    { $example
+        "TUPLE: test-maybe { value maybe{ fixnum string } } ;"
+        "test-maybe new value>>"
+        "f"
+    }
+}
+{ $see-also "unions" POSTPONE: maybe{ } ;

diff --git a/core/classes/maybe/summary.txt b/core/classes/maybe/summary.txt
new file mode 100644 (file)
index 0000000..c16a080
--- /dev/null
+++ b/core/classes/maybe/summary.txt
@@ -0,0 +1 @@
+Maybe classes

diff --git a/core/classes/mixin/mixin-docs.factor b/core/classes/mixin/mixin-docs.factor
index bc6cf49c2b5ed37d94cc0fd0f944941363270dbb..9dad65a203a50c8225987cc706c653b8823cc89b 100644 (file)
--- a/core/classes/mixin/mixin-docs.factor
+++ b/core/classes/mixin/mixin-docs.factor
@@ -16,7 +16,7 @@ ARTICLE: "mixins" "Mixin classes"
     mixin-class?
 }
 "Mixins are used to defines suites of behavior which are generally useful and can be applied to user-defined classes. For example, the " { $link immutable-sequence } " mixin can be used with user-defined sequences to make them immutable."
-{ $see-also "unions" "tuple-subclassing" } ;
+{ $see-also "unions" "maybes" "tuple-subclassing" } ;
 
 HELP: mixin-class
 { $class-description "The class of mixin classes." } ;

diff --git a/core/classes/tuple/tuple-docs.factor b/core/classes/tuple/tuple-docs.factor
index 8695c2572749aacd41e3bfe3c3ed0aa98d232765..8d17d6171f2f62a5565bfb987d36bc98fe2e90ef 100644 (file)
--- a/core/classes/tuple/tuple-docs.factor
+++ b/core/classes/tuple/tuple-docs.factor
@@ -16,7 +16,8 @@ ARTICLE: "slot-class-declaration" "Slot class declarations"
     { "The " { $link slots>tuple } " and " { $link >tuple } " words ensure that the values in the sequence satisfy the correct class predicates." }
     { { $link "tuple-redefinition" } " fills in new slots with initial values and ensures that changes to existing declarations result in incompatible values being replaced with the initial value of their respective slots." }
 }
-{ $subsections "slot-class-coercion" } ;
+{ $subsections "slot-class-coercion" }
+"The " { $link "maybes" } " are a useful way to specify class for an optional slot." ;
 
 ARTICLE: "slot-class-coercion" "Coercive slot declarations"
 "If the class of a slot is declared to be one of " { $link fixnum } " or " { $link float } ", then rather than testing values with the class predicate, writer words coerce values to the relevant type with " { $link >fixnum } " or " { $link >float } ". This may still result in error, but permits a wider range of values than a class predicate test. It also results in a possible loss of precision; for example, storing a large integer into a " { $link fixnum } " slot will silently overflow and discard high bits, and storing a ratio into a " { $link float } " slot may lose precision if the ratio is one which cannot be represented exactly with floating-point."
@@ -192,7 +193,7 @@ $nl
 }
 "Declaring a tuple class final prohibits other classes from subclassing it:"
 { $subsections POSTPONE: final }
-{ $see-also "call-next-method" "parameterized-constructors" "unions" "mixins" } ;
+{ $see-also "call-next-method" "parameterized-constructors" "unions" "mixins" "maybes" } ;
 
 ARTICLE: "tuple-introspection" "Tuple introspection"
 "In addition to the slot reader and writer words which " { $link POSTPONE: TUPLE: } " defines for every tuple class, it is possible to construct and take apart entire tuples in a generic way."

diff --git a/core/classes/union/union-docs.factor b/core/classes/union/union-docs.factor
index d5ee508bf6093ed474642008b432af653cc642cb..2335151e58cf7cc53109e30eed60beafb165482a 100644 (file)
--- a/core/classes/union/union-docs.factor
+++ b/core/classes/union/union-docs.factor
@@ -16,7 +16,7 @@ ARTICLE: "unions" "Union classes"
     union-class?
 }
 "Unions are used to define behavior shared between a fixed set of classes, as well as to conveniently define predicates."
-{ $see-also "mixins" "tuple-subclassing" } ;
+{ $see-also "mixins" "maybes" "tuple-subclassing" } ;
 
 ABOUT: "unions"
 

diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor
index 24052576c9be4f1ba4164d419b4a8085d45d3e48..5c2779b7eb6af47c6c57a99928e6d5109eaefc30 100644 (file)
--- a/core/words/words-docs.factor
+++ b/core/words/words-docs.factor
@@ -173,7 +173,7 @@ $nl
 
     { { { $snippet "\"superclass\"" } ", " { $snippet "\"predicate-definition\"" } } { $link "predicates" } }
 
-    { { $snippet "\"members\"" } { $link "unions" } }
+    { { $snippet "\"members\"" } { $link "unions" } { $link "maybes" } }
 
     { { $snippet "\"slots\"" } { $link "slots" } }