Partially completed adding documentation of SuccessorML Features.

doc/guide/src/MLBasisAnnotations.adoc

@@ -75,6 +75,46 @@ silence spurious messages, you can use `ignore e1`.
 +
 Report unused identifiers.
 
+Here are the annotations for enabling SuccessorML
+features.  The default value for all of these annotations is false,
+the SuccessorML features are all disabled by default.
+For information on the SuccessorML features
+see <:SuccessorML:>.
+
+* +allowDoDecls {false|true}+
++
+If `true` allows for the usage of do declarations.
+
+* +allowExtendedLiterals {false|true}+
++
+If `true` allows for the usage of extended literals.
+
+* +allowLineComments {false|true}+
++
+If `true` allows for the usage of line comments.
+
+* +allowOptBar {false|true}+
++
+If `true` allows for a pattern bar to optionally be placed before the
+first match in a case expression.
+
+* +allowOptSemicolon {false|true}+
++
+If `true` allows for a semicolon to optionally be placed after the last
+expression in a series.
+
+* +allowOrPats {false|true}+
++
+If `true` allows for the usage of disjunctive patterns.
+
+* +allowRecPunning {false|true}+
++
+If `true` allows for the usage record punning.
+
+* +allowSigWithtype {false|true}+
++
+If `true` allows for the usage the withtype keyword in signatures.
+
 == Next Steps ==
 
  * <:MLBasisAnnotationExamples:>

doc/guide/src/SuccessorML.adoc

@@ -7,3 +7,92 @@ using Standard ML as a starting point. The intention is for successor
 ML to be a living, evolving dialect of ML that is responsive to
 community needs and advances in language design, implementation, and
 semantics.
+
+== SuccessorML Features in MLton ==
+
+The following SuccessorML features have been implemented in MLton.
+The features are disabled by default, for information about enabling
+these features see their corresponding <:MLBasisAnnotations:>.
+
+* Do Declarations
++
+Evaluating functions for their side effects is a common idiom seen
+in SML.  This feature allows for the same functionality but in an
+alternative syntax.  It is requried that the expression being
+evaluated has the type of unit in order to use a do declaration.
++
+Commonly one may perform either of the following:
++
+----
+val _ = print "Hello world.\n"
+val () = print "Hello world.\n"
+----
++
+Instead the following syntax may be used:
++
+----
+do print "Hello world.\n"
+----
+
+* Extended Literals
++
+This feature allows for binary literals to be used.
+Additionally underscores may be used throughout
+literals to group digits together for convenience.
++
+Below are some examples of extended literal syntax.
++
+----
+val b = 0b10101
+val bw = 0wb1010
+val x = 4_327_829
+----
+
+* Line Comments
++
+Line comments may be may be started with ++(*)++.
++
+----
+(*) This is a line comment
+----
++
+Please note that with this feature enabled the following
+SML code which would previously compile will now result
+in a compilation error.
++
+----
+(*)
+val x = 0 (*) This line is no-longer part of a block comment
+*)
+----
+
+* Optional Pattern Bars
++
+Information about optional pattern bars
+
+* Optional Semicolons
++
+Information about optional semicolons
+
+* Disjunctive (Or) Patterns
++
+This feature allows for being able to utilize ``or-patterns''.
+One can ``or'' multiple matches together without having to re-write
+the same resultant right-hand-side expression.  Note that
+disjunctive patterns require an additional surrounding parenthesis.
++
+For example `exp` could be matched as follows:
++
+----
+case exp of
+    (A | B | C) =>  1
+  | (D | E) => 2
+----
+
+* Record Punning
++
+Information about record punning
+
+* Withtype for Signatures
++
+Information about withtype for signatures