docs: revamp scale factor comment

Author: QGarchery

src/ChainlinkOracle.sol

@@ -45,20 +45,21 @@ contract ChainlinkOracle is IOracle {
         BASE_FEED_2 = baseFeed2;
         QUOTE_FEED_1 = quoteFeed1;
         QUOTE_FEED_2 = quoteFeed2;
-        // Let pB1 and pB2 be the base prices, and pQ1 and pQ2 the quote prices (price of 1e(decimals) asset), in a
-        // common quote currency.
-        // Chainlink feeds return pB1*b1FeedPrecision, pB2*b2FeedPrecision, pQ1*q1FeedPrecision and pQ2*q2FeedPrecision.
-        // `price()` should return 1e36 * (pB1/1e(b1Decimals) * pB2/1e(b2Decimals)) / (pQ1/1e(q1Decimals) *
-        // pQ2/1e(q2Decimals))
-        // Yet `price()` returns (pB1*1e(b1FeedPrecision) * pB2*1e(b2FeedPrecision) * SCALE_FACTOR) /
-        // (pQ1*1e(q1FeedPrecision) * pQ2*1e(q2FeedPrecision))
-        // So 1e36 * (pB1/1e(b1Decimals) * pB2/1e(b2Decimals)) / (pQ1/1e(q1Decimals) * pQ2/1e(q2Decimals)) =
-        // (pB1*1e(b1FeedPrecision) * pB2*1e(b2FeedPrecision) * SCALE_FACTOR) / (pQ1*1e(q1FeedPrecision) *
-        // pQ2*1e(q2FeedPrecision))
-        // So SCALE_FACTOR = 1e36 / 1e(b1Decimals) / 1e(b2Decimals) * 1e(q1Decimals) * 1e(q2Decimals) *
-        // 1e(q1FeedPrecision) * 1e(q2FeedPrecision) / 1e(b1FeedPrecision) / 1e(b2FeedPrecision)
-        //                 = 1e(36 + q1Decimals + q2Decimals + q1FeedPrecision + q2FeedPrecision - b1Decimals -
-        // b2Decimals - b1FeedPrecision - b2FeedPrecision)
+        // Let pB1 and pB2 be the base prices, and pQ1 and pQ2 the quote prices (price taking into account the
+        // decimals of both tokens), in a common currency.
+        // Let dB1, dB2, dB3, and dQ1, dQ2, dQ3 be the decimals of the tokens involved.
+        // For example, pB1 is the number of 1e(dB2) of the second base asset that can be obtained from 1e(dB1) of
+        // the first base asset.
+        // We notably have dB3 = dQ3, because those two quantities are the decimals of the same common currency.
+        // Let fpB1, fpB2, fpQ1 and fpQ2 be the feed precision of the corresponding prices.
+        // Chainlink feeds return pB1*1e(fpB1), pB2*1e(fpB2), pQ1*1e(fpQ1) and pQ2*1e(fpQ2).
+        // Because the Blue oracle does not take into account decimals, `price()` should return
+        // 1e36 * (pB1*1e(dB2-dB1) * pB2*1e(dB3-dB2)) / (pQ1*1e(dQ2-dQ1) * pQ2*1e(dQ3-dQ2))
+        // Yet `price()` returns (pB1*1e(fpB1) * pB2*1e(fpB2) * SCALE_FACTOR) / (pQ1*1e(fpQ1) * pQ2*1e(fpQ2))
+        // So 1e36 * pB1 * pB2 * 1e(-dB1) / (pQ1 * pQ2 * 1e(-dQ1)) =
+        // (pB1*1e(fpB1) * pB2*1e(fpB2) * SCALE_FACTOR) / (pQ1*1e(fpQ1) * pQ2*1e(fpQ2))
+        // So SCALE_FACTOR = 1e36 / 1e(dB1) * 1e(dQ1) / 1e(fpB1) / 1e(fpB2) * 1e(fpQ1) * 1e(fpQ2)
+        //                 = 1e(36 + dQ1 + fpQ1 + fpQ2 - dB1 - fpB1 - fpB2)
         SCALE_FACTOR = 10
             ** (
                 36 + quoteTokenDecimals + quoteFeed1.getDecimals() + quoteFeed2.getDecimals() - baseTokenDecimals