doc(patterns): documentation for preventative errors

Author: j-mie6

parsley/shared/src/main/scala/parsley/errors/patterns.scala

@@ -36,8 +36,6 @@ object patterns {
       * @define atomicNonTerminal
       *     when this parser is not to be considered as a terminal error, use `atomic` around the ''entire'' combinator to
       *     allow for backtracking if this parser succeeds (and therefore fails).
-      *
-      * @define Ensures this parser does not succeed, failing with a
       */
     implicit final class VerifiedErrors[P, A](p: P)(implicit con: P => Parsley[A]) {
         /** Ensures this parser does not succeed, failing with a specialised error based on this parsers result if it does.
@@ -117,7 +115,7 @@ object patterns {
           * the given `errGen` with width the same as the parsed data. However, if this parser fails, no input is consumed
           * and an empty error is generated. This parser will produce no labels if it fails.
           *
-          * @param err
+          * @param err the generator that produces the error message.
           * @since 4.4.0
           * @note $autoAmend
           * @note $atomicNonTerminal
@@ -134,20 +132,102 @@ object patterns {
         @inline private def verifiedWithVanillaRaw(reasonGen: A => Option[String]) = verifiedWithVanilla(_ => VanillaGen.RawItem, reasonGen)
     }
 
-    // TODO: document!
+    /** This class exposes combinators related to the ''Preventative Errors'' parser design pattern.
+      *
+      * This extension class operates on values that are convertible to parsers. The combinators it enables
+      * allow for the parsing of known illegal values, providing richer error messages in case they succeed.
+      *
+      * @constructor This constructor should not be called manually, it is designed to be used via Scala's implicit resolution.
+      * @param p the value that this class is enabling methods on.
+      * @param con a conversion that allows values convertible to parsers to be used.
+      * @tparam P the type of base value that this class is used on (the conversion to `Parsley`) is summoned automatically.
+      * @since 4.4.0
+      *
+      * @define autoAmend
+      *     when this combinator fails (and not this parser itself), it will generate errors rooted at the start of the
+      *     parse (as if [[parsley.errors.combinator$.amend `amend`]] had been used) and the caret will span the entire
+      *     successful parse of this parser.
+      *
+      * @define atomicNonTerminal
+      *     when this parser is not to be considered as a terminal error, use `atomic` around the ''entire'' combinator to
+      *     allow for backtracking if this parser succeeds (and therefore fails).
+      */
     implicit final class PreventativeErrors[P, A](p: P)(implicit con: P => Parsley[A]) {
-        // TODO: document and test
+        // TODO: test
+        /** Ensures this parser does not succeed, failing with a specialised error based on this parsers result if it does.
+          *
+          * If this parser succeeds, input is consumed and this combinator will fail, producing an error message
+          * based on the parsed result. However, if this parser fails, no input is consumed and this combinator succeeds.
+          * This parser will produce no evidence of running if it succeeds.
+          *
+          * @param msggen the function that generates the error messages from the parsed value.
+          * @since 4.4.0
+          * @note $autoAmend
+          * @note $atomicNonTerminal
+          */
         def preventativeFail(msggen: A => Seq[String]): Parsley[Unit] = this.preventWith(new SpecialisedGen[A] {
             override def messages(x: A) = msggen(x)
         })
-        // TODO: document and test
+
+        // TODO: test
+        /** Ensures this parser does not succeed, failing with a fixed specialised error if it does.
+          *
+          * If this parser succeeds, input is consumed and this combinator will fail, producing an error message with the
+          * given messages. However, if this parser fails, no input is consumed and this combinator succeeds.
+          * This parser will produce no evidence of running if it succeeds.
+          *
+          * @param msg0 the first message in the error message.
+          * @param msgs the remaining messages that will make up the error message.
+          * @since 4.4.0
+          * @note $autoAmend
+          * @note $atomicNonTerminal
+          */
         def preventativeFail(msg0: String, msgs: String*): Parsley[Unit] = this.preventativeFail(_ => msg0 +: msgs)
-        // TODO: document and test
+
+        // TODO: test
+        /** Ensures this parser does not succeed, failing with a vanilla error with an unexpected message and caret spanning the parse and a reason generated
+          * from this parser's result.
+          *
+          * If this parser succeeds, input is consumed and this combinator will fail, producing an unexpected message the same width as
+          * the parse along with a reason generated from the successful parse along with the given labels. However, if this parser fails, no input is
+          * consumed and this combinator succeeds. This parser will produce no evidence of running if it succeeds.
+          *
+          * @param reason a function that produces a reason for the error given the parsed result.
+          * @param labels the labels that should be expected if this parser hadn't succeeded.
+          * @since 4.4.0
+          * @note $autoAmend
+          * @note $atomicNonTerminal
+          */
         def preventativeExplain(reason: A => String, labels: String*): Parsley[Unit] = this.preventWithVanillaRaw(x => Some(reason(x)), labels: _*)
-        // TODO: document and test
+
+        // TODO: test
+        /** Ensures this parser does not succeed, failing with a vanilla error with an unexpected message and caret spanning the parse and a given reason.
+          *
+          * If this parser succeeds, input is consumed and this combinator will fail, producing an unexpected message the same width as
+          * the parse along with the given reason and given labels. However, if this parser fails, no input is consumed and this combinator succeeds.
+          * This parser will produce no evidence of running if it succeeds.
+          *
+          * @param reason the reason that this parser is illegal.
+          * @param labels the labels that should be expected if this parser hadn't succeeded.
+          * @since 4.4.0
+          * @note $autoAmend
+          * @note $atomicNonTerminal
+          */
         def preventativeExplain(reason: String, labels: String*): Parsley[Unit] = this.preventativeExplain(_ => reason, labels: _*)
 
-        // TODO: document and test
+        // TODO: test
+        /** Ensures this parser does not succeed, failing with an error as described by the given `ErrorGen` object.
+          *
+          * If this parser succeeds, input is consumed and this combinator will fail, producing an error message using
+          * the given `errGen` with width the same as the parsed data along with the given labels. However, if this parser
+          * fails, no input is consumed and this combinator succeeds. This parser will produce no evidence of running if it succeeds.
+          *
+          * @param err the generator that produces the error message.
+          * @param labels the labels that should be expected if this parser hadn't succeeded.
+          * @since 4.4.0
+          * @note $autoAmend
+          * @note $atomicNonTerminal
+          */
         def preventWith(err: ErrorGen[A], labels: String*) = {
             val inner: Parsley[Either[(A, Int), Unit]] = withWidth(atomic(con(p)).newHide) <+> unit
             val labelledErr = labels match {