docs(angular): document the constraints on the boolean attribute helper

Author: thetaPC

packages/angular/src/common/utils/boolean-attribute.ts

@@ -12,18 +12,13 @@
  * Strings are coerced the same way Angular's `booleanAttribute` coerces them, so `''` (a bare
  * attribute) becomes `true` and `'false'` becomes `false`.
  *
- * Unlike Angular's `booleanAttribute`, `null` and `undefined` are passed through rather than
- * coerced to `false`. Components frequently treat them as a state distinct from `false`, and both
- * reach inputs routinely from the `async` pipe before its first emission and from form control
- * values:
+ * Angular's own `booleanAttribute` is not used because it coerces `null` and `undefined` to
+ * `false`. Components frequently treat those as a state distinct from `false`, such as
+ * `ion-item`'s `detail` resolving `undefined` to a computed default, and both reach inputs
+ * routinely from the `async` pipe before its first emission and from form control values.
  *
- * ```tsx
- * // `undefined` means "decide based on the mode", which is not the same as `false`
- * const showDetail = detail !== undefined ? detail : mode === 'ios';
- *
- * // a strict comparison also behaves differently for `null` than it does for `false`
- * const showHandle = handle !== false;
- * ```
+ * The parameter type is what Angular derives `ngAcceptInputType_*` from, so it decides which
+ * template bindings compile. Widening it to `unknown` would let any expression through.
  *
  * Declared as a function rather than an arrow constant because Angular has to resolve input
  * transforms statically when compiling a library in partial compilation mode.