Updated documentation with suggested changes

src/internal/core/index.ts

@@ -22,7 +22,7 @@ export type Failure = { success: false };
 export type Result<T> = Success<T> | Failure;
 
 /**
- * The function used by a parser to determine if it succeeds or fails.
+ * The function used by a parser 
  */
 export type ParserHandler<T> = (input: string, index: number, state: any) => Result<T>
 
@@ -78,7 +78,7 @@ export class Parser<T> {
 	}
 
 	/**
-	 * A function that maps the result of the parse with the provided function if successful, and returns a {@link Failure} 
+	 * A method that maps the result of the parse with the provided function if successful, and returns a {@link Failure} 
 	 * otherwise.
 	 * 
 	 * @param fn The function used to map the output of the parser.
@@ -95,7 +95,8 @@ export class Parser<T> {
 	}
 
 	/**
-	 * A function that returns the plaintext related to the {@link Success} and a {@link Failure} otherwise.
+	 * A method that returns the portion of the input that matches this {@link Parser Parser's} language and a {@link Failure} 
+	 * if the parse failed.
 	 * 
 	 * @returns The plaintext related to the successful parse, and a {@link Failure} if the parse failed.
 	 */
@@ -111,8 +112,7 @@ export class Parser<T> {
 	}
 
 	/**
-	 * A function that returns a {@link Parser} that must succeed at least of `min` times in order to return 
+	 * A method that returns a {@link Parser} that matches at least `min` repetitions of this parser.
-	 * a {@link Success} and returns a {@link Failure} otherwise.
 	 * 
 	 * @param min The minimum amount of times this parse must succeed to return a {@link Success}.
 	 * @returns A Parser that returns a {@link Success} object it matches enough times, and a {@link Failure} otherwise.
@@ -138,7 +138,8 @@ export class Parser<T> {
 	}
 
 	/**
-	 * A function that checks if the supplied separator appears between this separator's value.
+	 * A method that returns a new {@link Parser} that matches at least `min` times, with each repetition separated
+	 * by `separator`.
 	 * 
 	 * @param separator The parser representing the separator that must appear between this parser's value.
 	 * @param min The minimum amount of times the separator must appear.
@@ -158,8 +159,8 @@ export class Parser<T> {
 	}
 
 	/**
-	 * A function that attempts to match this parser, but returns a {@link Success} object with the 
+	 * A method that returns a new {@link Parser} that attempts to match, but returns a {@link Success} with the value `null`
-	 * value `null` if it fails.
+	 * on failure.
 	 * 
 	 * @returns A {@link Success} object.
 	 */
@@ -239,10 +240,8 @@ export function seq(parsers: Parser<any>[], select?: number): Parser<any> {
 }
 
 /**
- * A function that returns a {@link Parser} that goes through the parsers provided, in order, and checks if each succeeds.
+ * A function that returns a {@link Parser} that goes through the parsers provided, in order, and checks if any succeed.
- * If one fails, the next parser is tested, and this pattern is continued until the final parser is tested, at which point
+ * The returned parser produces the result of the first element of `parsers` to succeed, or a failure if none do.
- * the parser will return a {@link Failure} if it still fails. If any of the parsers succeed, the resulting {@link Success}
- * is returned immediately.
  * 
  * @param parsers The {@link Parser Parsers} that should be used.
  * @returns A {@link Parser} that returns the first {@link Success} from the supplied parsers.
@@ -261,7 +260,7 @@ export function alt(parsers: Parser<any>[]): Parser<any> {
 }
 
 /**
- * A function that returns a {@link Parser} that always succeeds, returning a {@link Success} object with the supplied value.
+ * A function that returns a constant {@link Parser}.
  * 
  * @param value The value to be used in the returned {@link Success} object.
  * @returns A {@link Parser} that always returns a {@link Success} with the specified value.
@@ -317,7 +316,10 @@ export const crlf = str('\r\n');
 /** A {@link Parser} that matches for any valid new line sequences. */
 export const newline = alt([crlf, cr, lf]);
 
-/** A {@link Parser} that succeeds so long as it is not at the end of the input string. */
+/** 
+ * A {@link Parser} that succeeds so long as it is not at the end of the input string and returns the value of
+ * the next character. 
+ */
 export const char = new Parser((input, index, _state) => {
 	if ((input.length - index) < 1) {
 		return failure();