Minor natspec comments improvements

Author: acenolaza

contracts/NormalizedApi3ReaderProxyV1.sol

@@ -5,7 +5,7 @@ import "./interfaces/INormalizedApi3ReaderProxyV1.sol";
 
 /// @title An immutable proxy contract that converts a Chainlink
 /// AggregatorV2V3Interface feed output to 18 decimals to conform with
-/// IApi3ReaderProxy decimal standard
+/// IApi3ReaderProxy decimal convention
 /// @dev This contract implements the AggregatorV2V3Interface to be compatible
 /// with Chainlink aggregators. This allows the contract to be used as a drop-in
 /// replacement for Chainlink aggregators in existing dApps.
@@ -44,6 +44,15 @@ contract NormalizedApi3ReaderProxyV1 is INormalizedApi3ReaderProxyV1 {
 
     /// @notice Returns the price of the underlying Chainlink feed normalized to
     /// 18 decimals.
+    /// @dev Fetches an `int256` answer from the Chainlink feed and scales it
+    /// to 18 decimals using pre-calculated factors. The result is cast to
+    /// `int224` to conform to the `IApi3ReaderProxy` interface.
+    /// IMPORTANT: If the normalized `int256` value is outside the `int224`
+    /// range, this cast causes silent truncation and data loss. Deployers
+    /// must verify that the source feed's characteristics (value magnitude
+    /// and original decimals) ensure the 18-decimal normalized value fits
+    /// `int224`. Scaling arithmetic (prior to cast) reverts on `int256`
+    /// overflow.
     /// @return value The normalized signed fixed-point value with 18 decimals
     /// @return timestamp The updatedAt timestamp of the feed
     function read()

contracts/adapters/ScaledApi3FeedProxyV1.sol

@@ -133,13 +133,14 @@ contract ScaledApi3FeedProxyV1 is IScaledApi3FeedProxyV1 {
     /// @notice Reads a value from the underlying `IApi3ReaderProxy` and
     /// scales it to `targetDecimals`.
     /// @dev Reads an `int224` value (assumed to be 18 decimals) from the
-    /// underlying `IApi3ReaderProxy` and scales it to `targetDecimals`.
-    /// The initial `int224` proxy value is widened to `int256` before scaling.
-    /// The scaling arithmetic (`value * factor` or `value / factor`) is then
-    /// performed using `int256` types. This allows the scaled result to exceed
-    /// the `int224` range, provided it fits within `int256`.
-    /// Arithmetic operations will revert on overflow or underflow
-    /// (e.g., if `value * scalingFactor` exceeds `type(int256).max`).
+    /// underlying `IApi3ReaderProxy`. This value is then scaled to
+    /// `targetDecimals` using pre-calculated factors. The scaling arithmetic
+    /// (e.g., `proxyValue * scalingFactor`) involves an `int224` (`proxyValue`)
+    /// and an `int256` (`scalingFactor`). `proxyValue` is implicitly promoted
+    /// to `int256` for this operation, resulting in an `int256` value.
+    /// This allows the scaled result to exceed the `int224` range, provided
+    /// it fits within `int256`. Arithmetic operations will revert on `int256`
+    /// overflow. The function returns the scaled value as an `int256`.
     /// @return value The scaled signed fixed-point value with `targetDecimals`.
     /// @return timestamp The timestamp from the underlying proxy.
     function _read() internal view returns (int256 value, uint32 timestamp) {