Merge pull request #153 from ALCops/docs/pc0038-fc0007-lc0089-fielderror

docs(PC0038, FC0007, LC0089): document FieldError as a flow terminator

Author: Arthurvdv

content/docs/analyzers/FormattingCop/FC0007.md

@@ -10,7 +10,7 @@ linkTitle = 'FC0007'
   ignoreObsolete = true
 +++
 
-Multi-line control-flow blocks (`if`, `case`, `repeat`, `while`, `for`, `foreach`) and scope-leaving statements (`exit`, built-in `Error(...)`) read more clearly when they are visually separated from surrounding code by a blank line. The rule reports the exact spot where a separator is missing so it can be inserted with a single keystroke, without touching the logic.
+Multi-line control-flow blocks (`if`, `case`, `repeat`, `while`, `for`, `foreach`) and scope-leaving statements (`exit`, built-in `Error(...)` and `FieldError(...)`) read more clearly when they are visually separated from surrounding code by a blank line. The rule reports the exact spot where a separator is missing so it can be inserted with a single keystroke, without touching the logic.
 
 FC0007 is **disabled by default** and fully configurable. Enable it in your project's `.ruleset.json` (or via `AL: Configure ruleset`) and, optionally, tune the individual checks in `alcops.json`.
 
@@ -70,7 +70,7 @@ The rule runs four independent checks. Each check can be toggled or narrowed via
 |---|---|---|
 | Blank line **before** a control-flow block | A multi-line `if`, `case`, `repeat`, `while`, `for`, or `foreach` immediately follows another statement in the same block. | `ControlFlowBefore` |
 | Blank line **after** a control-flow block | A non-control-flow statement immediately follows the closing `end` (or `until`) of a multi-line control-flow block. | `ControlFlowAfter` |
-| Blank line before a **scope-leaving** statement | `exit`, built-in `Error(...)`, or both follow a sibling statement in the same statement list without a whitespace-only line between them. | `ScopeLeavingMode` |
+| Blank line before a **scope-leaving** statement | `exit`, a built-in `Error(...)` / `FieldError(...)` call, or both follow a sibling statement in the same statement list without a whitespace-only line between them. | `ScopeLeavingMode` |
 | Blank line before **`else`** in an `if ... end else` construct | The closing `end` and the `else` keyword sit on adjacent lines instead of being separated by a blank line. Opt-in. | `ElseChainBeforeMode` |
 
 Single-line control-flow statements (e.g. `if Flag then Message('x');` on one line) are excluded from the *before* / *after* checks by default. Include them with `OneLinerMode`.
@@ -97,7 +97,7 @@ exit;                       // OK: the empty line above still counts as a separa
 
 - The symbol is obsolete
 - Adjacent case branches inside a `case` statement (the check operates on the surrounding block, not on branches)
-- An `exit` or `Error(...)` used directly as a `then` / `else` branch (the containing `if` is governed by the control-flow settings)
+- An `exit`, `Error(...)` or `FieldError(...)` used directly as a `then` / `else` branch (the containing `if` is governed by the control-flow settings)
 - Any statement immediately after `begin` or immediately before `end` (the block braces already act as separators)
 
 ### Configuration
@@ -120,7 +120,7 @@ All settings live under a single `StatementBlockSpacing` object in `alcops.json`
 |---|---|---|---|---|
 | `ControlFlowBefore` | boolean | `true` | `true` / `false` | Require a blank line before a multi-line control-flow block when it follows another statement in the same block. |
 | `ControlFlowAfter` | boolean | `true` | `true` / `false` | Require a blank line after a multi-line control-flow block when a non-control-flow statement follows it directly. |
-| `ScopeLeavingMode` | string | `"ExitAndError"` | `"Off"`, `"ExitOnly"`, `"ErrorOnly"`, `"ExitAndError"` | Which scope-leaving statements require a preceding blank line. |
+| `ScopeLeavingMode` | string | `"ExitAndError"` | `"Off"`, `"ExitOnly"`, `"ErrorOnly"`, `"ExitAndError"` | Which scope-leaving statements require a preceding blank line. `ErrorOnly` and `ExitAndError` cover the built-in `Error(...)` as well as `Record.FieldError(...)` / `FieldRef.FieldError(...)`. |
 | `ElseChainBeforeMode` | string | `"Off"` | `"Off"`, `"RequireBlank"` | Whether the `else` keyword of an `if ... end else` construct must sit on its own after a blank line. |
 | `OneLinerMode` | string | `"None"` | `"None"`, `"All"` | Whether single-line control-flow statements participate in the `ControlFlowBefore` / `ControlFlowAfter` checks. |
 
@@ -142,7 +142,7 @@ Turn every check off and re-enable individual ones:
 }
 ```
 
-With this configuration the rule flags only the space before a multi-line block and the space before an `Error(...)` call; `exit` statements, trailing blanks and one-liners are ignored.
+With this configuration the rule flags only the space before a multi-line block and the space before an `Error(...)` or `FieldError(...)` call; `exit` statements, trailing blanks and one-liners are ignored.
 
 #### Enforcing blank line before `else`
 

content/docs/analyzers/LinterCop/LC0089.md

@@ -48,6 +48,8 @@ begin
 end;
 {{< /highlight >}}
 
+A guard clause is an `if` whose only statement leaves the current flow: `exit`, `break`, `continue`, `CurrReport.Skip()` / `CurrReport.Break()` / `CurrReport.Quit()` (and the `CurrXMLport` equivalents), or a call to a built-in method that never returns — `Error(...)`, `Record.FieldError(...)` or `FieldRef.FieldError(...)`. A user-defined procedure that happens to be named `Error` or `FieldError` is a normal call and keeps its increment.
+
 For the full scoring model — how nesting penalties, logical operators, recursion, and compensating usages like `else if` are calculated — see [LC0090](../lc0090/).
 
 ### Increment diagnostics

content/docs/analyzers/PlatformCop/PC0038.md

@@ -50,7 +50,7 @@ Triggers are intentionally excluded from this rule, even when they declare a ret
 
 ### Exception
 
-Paths that end with `Error(...)` are accepted:
+Paths that end with a built-in call that never returns — `Error(...)`, `Record.FieldError(...)` or `FieldRef.FieldError(...)` — are accepted:
 
 {{< highlight al >}}
 procedure GetAmount(IncludeVat: Boolean): Decimal
@@ -60,8 +60,18 @@ begin
     else
         Error('Prices without VAT are not supported.');
 end;
+
+procedure GetUnitPrice(Item: Record Item): Decimal
+begin
+    if Item."Unit Price" > 0 then
+        exit(Item."Unit Price")
+    else
+        Item.FieldError("Unit Price", 'must be positive.');
+end;
 {{< /highlight >}}
 
+Only the built-in methods qualify; a user-defined procedure that happens to be named `Error` or `FieldError` does not terminate the path.
+
 A named return variable passed to a `var` parameter, or used as the receiver of a call, counts as assigned:
 
 {{< highlight al >}}