HF-131 (7/7): documentation

docs/guide/types-of-errors.md

@@ -9,7 +9,7 @@ tags:
   - "#CYCLE!"
   - "#ERROR!"
   - "#LIC!"
-  - division by zero
+  - "#SPILL!"
 ---
 
 # Types of errors
@@ -37,4 +37,43 @@ according to the language settings.
 | #VALUE! | Wrong type of argument | It occurs when a formula tries to improperly use different types of data. For example, you will see this error when you will try to add a string to a number. |
 | #CYCLE! | Circular reference | It occurs when a formula refers to its own cell, both directly and indirectly. |
 | #ERROR! | An error occurred | It indicates that there is an unknown error in a formula. |
-| #LIC! | License key problem | It occurs when the license key is missing or invalid, when it has expired and your [license terms](license-key.md#license-key-notifications) stop it from working after that, or when the function is not included in the [feature package](license-key.md#feature-packages-and-add-ons) your license key grants. |
+| #LIC! | License key problem | It occurs when the license key is missing or invalid, when it has expired and your [license terms](license-key.md#license-key-notifications) stop it from working after that, or when the function is not included in the [feature package](license-key.md#feature-packages-and-add-ons) your license key grants. |
+| #SPILL! | No space for array result | It occurs when an array formula's result would overwrite one or more non-empty cells, so it has nowhere to spill into. |
+
+## Error messages and explanations
+
+An error's `message` property states the specific cause within its type — for
+example, distinguishing *why* a formula returned `#NUM!` rather than only that it
+did. HyperFormula does not turn that message into a longer, plain-language
+explanation, and does not call out to a language model to generate one. An
+application built on top of HyperFormula that wants to rephrase an error for its
+end users — in natural language, or translated beyond the languages HyperFormula
+ships with — should do so at the application layer, using the `type` and
+`message` HyperFormula already provides as its input.
+
+## Finding out where an error came from
+
+Besides `type` and `message`, a `DetailedCellError` tells you what produced the
+error and, when it was a function rejecting one of its own arguments, which
+argument. `originFunction` names a function or an operator helper when one of them
+rejected a value, and otherwise names what built the error: `reference` for a
+reference that cannot be resolved, `removed reference` for one destroyed by
+removing rows or columns, `parser` for a formula that could not be parsed, `user
+input` for an error value typed into a cell, `literal` for one written into a
+formula, or `array literal` for an array literal whose rows differ in length.
+`argumentIndex` is zero-based.
+
+```javascript
+const hf = HyperFormula.buildFromArray(
+  [['=SUM(SQRT(-1))'], ['=DATE(2000, "x", 1)'], ['=SUM(A99999999999:A99999999999)']],
+  { licenseKey: 'gpl-v3' }
+);
+
+hf.getCellValue({ sheet: 0, row: 0, col: 0 }).originFunction; // 'SQRT', not 'SUM'
+hf.getCellValue({ sheet: 0, row: 1, col: 0 }).argumentIndex;  // 1, the second argument
+hf.getCellValue({ sheet: 0, row: 2, col: 0 }).originFunction; // 'reference'
+```
+
+The first occurrence wins, so a function that only read an error never replaces
+the identity already on it. `address` points at the cell where the error arose,
+which is not always the cell you read it from.