docs: Clarify that not all errors can be avoided

eemeli · eemeli · commit 167365befdae · 2026-05-11T12:15:18.000+03:00
diff --git a/docs/01_intro.md b/docs/01_intro.md
@@ -23,7 +23,7 @@ This library:
 
 - Supports both YAML 1.1 and YAML 1.2 and all common data schemas,
 - Passes all of the [yaml-test-suite](https://github.com/yaml/yaml-test-suite) tests,
-- Can accept any string as input without throwing, parsing as much YAML out of it as it can, and
+- Can accept nearly any string as input without throwing, parsing as much YAML out of it as it can, and
 - Supports parsing, modifying, and writing YAML comments and blank lines.
 
 The library is released under the ISC open source license, and the code is [available on GitHub](https://github.com/eemeli/yaml/).
diff --git a/docs/02_parse_stringify.md b/docs/02_parse_stringify.md
@@ -40,7 +40,9 @@ YAML.parse(file)
 
 The returned value will match the type of the root value of the parsed YAML document, so Maps become objects, Sequences arrays, and scalars result in nulls, booleans, numbers and strings.
 
-`YAML.parse` may throw on error, and it may log warnings using `console.warn`. It only supports input consisting of a single YAML document; for multi-document support you should use [`YAML.parseAllDocuments`](#parsing-documents).
+`YAML.parse` will throw on error, and it may log warnings using `console.warn`.
+It only supports input consisting of a single YAML document;
+for multi-document support you should use [`YAML.parseAllDocuments`](#parsing-documents).
 
 ## YAML.stringify
 
diff --git a/docs/04_documents.md b/docs/04_documents.md
@@ -40,8 +40,10 @@ doc.contents
 //   range: [ 0, 180, 180 ] }
 ```
 
-These functions should never throw,
-provided that `str` is a string and the `options` are valid.
+These functions should not throw,
+provided that `str` is a reasonable string and the `options` are valid.
+Specially crafted inputs may still result in errors due to resource exhaustion,
+such as stack overflows.
 Errors and warnings are included in the documents' `errors` and `warnings` arrays.
 In particular, if `errors` is not empty
 it's likely that the document's parsed `contents` are not entirely correct.
diff --git a/docs/07_parsing_yaml.md b/docs/07_parsing_yaml.md
@@ -49,7 +49,8 @@ At the end of input, `lex()` should be called a final time with `incomplete: fal
 
 Internally, the lexer operates a state machine that determines how it parses its input.
 Initially, the lexer is always in the `stream` state.
-The lexer constructor and its `lex()` method should never throw an error.
+The lexer constructor and its `lex()` method should never throw an error,
+except due to resource exhaustion.
 
 All tokens are identifiable either by their exact value or their first character.
 In addition to slices of the input stream, a few control characters are additionally used within the output.
