Skip to content

Commit 2b290cd

Browse files
PaulRBergPaulRBerg
committed
docs: improve writing
1 parent d8ddd6e commit 2b290cd

5 files changed

Lines changed: 46 additions & 47 deletions

File tree

‎src/Common.sol‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -485,7 +485,7 @@ function mulDiv(uint256 x, uint256 y, uint256 denominator) pure returns (uint256
485485
/// $$
486486
///
487487
/// Requirements:
488-
/// - All from {mulDiv}.
488+
/// - Refer to the requirements in {mulDiv}.
489489
/// - The result must fit in uint256.
490490
///
491491
/// @param x The multiplicand as an unsigned 60.18-decimal fixed-point number.
@@ -533,7 +533,7 @@ function mulDiv18(uint256 x, uint256 y) pure returns (uint256 result) {
533533
/// - Unlike {mulDiv}, the result is rounded toward zero.
534534
///
535535
/// Requirements:
536-
/// - All from {mulDiv}.
536+
/// - Refer to the requirements in {mulDiv}.
537537
/// - None of the inputs can be `type(int256).min`.
538538
/// - The result must fit in int256.
539539
///
@@ -598,21 +598,21 @@ function sqrt(uint256 x) pure returns (uint256 result) {
598598
return 0;
599599
}
600600

601-
// For our first guess, we get the biggest power of 2 which is smaller than the square root of x.
601+
// For our first guess, we calculate the biggest power of 2 which is smaller than the square root of x.
602602
//
603603
// We know that the "msb" (most significant bit) of x is a power of 2 such that we have:
604604
//
605605
// $$
606606
// msb(x) <= x <= 2*msb(x)$
607607
// $$
608608
//
609-
// We write $msb(x)$ as $2^k$ and we get:
609+
// We write $msb(x)$ as $2^k$, and we get:
610610
//
611611
// $$
612612
// k = log_2(x)
613613
// $$
614614
//
615-
// Thus we can write the initial inequality as:
615+
// Thus, we can write the initial inequality as:
616616
//
617617
// $$
618618
// 2^{log_2(x)} <= x <= 2*2^{log_2(x)+1} \\

‎src/sd59x18/Constants.sol‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,11 @@ SD59x18 constant EXP2_MAX_INPUT = SD59x18.wrap(uEXP2_MAX_INPUT);
2020
int256 constant uHALF_UNIT = 0.5e18;
2121
SD59x18 constant HALF_UNIT = SD59x18.wrap(uHALF_UNIT);
2222

23-
/// @dev $log2(10)$ as an SD59x18 number.
23+
/// @dev $log_2(10)$ as an SD59x18 number.
2424
int256 constant uLOG2_10 = 3_321928094887362347;
2525
SD59x18 constant LOG2_10 = SD59x18.wrap(uLOG2_10);
2626

27-
/// @dev $log2(e)$ as an SD59x18 number.
27+
/// @dev $log_2(e)$ as an SD59x18 number.
2828
int256 constant uLOG2_E = 1_442695040888963407;
2929
SD59x18 constant LOG2_E = SD59x18.wrap(uLOG2_E);
3030

‎src/sd59x18/Math.sol‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -105,11 +105,11 @@ function ceil(SD59x18 x) pure returns (SD59x18 result) {
105105
/// values separately.
106106
///
107107
/// Notes:
108-
/// - All from {Common.mulDiv}.
108+
/// - Refer to the notes in {Common.mulDiv}.
109109
/// - The result is rounded toward zero.
110110
///
111111
/// Requirements:
112-
/// - All from {Common.mulDiv}.
112+
/// - Refer to the requirements in {Common.mulDiv}.
113113
/// - None of the inputs can be `MIN_SD59x18`.
114114
/// - The denominator must not be zero.
115115
/// - The result must fit in SD59x18.
@@ -133,7 +133,7 @@ function div(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
133133
yAbs = yInt < 0 ? uint256(-yInt) : uint256(yInt);
134134
}
135135

136-
// Compute the absolute value (x*UNIT÷y). The resulting value must fit in int256.
136+
// Compute the absolute value (x*UNIT÷y). The resulting value must fit in SD59x18.
137137
uint256 resultAbs = Common.mulDiv(xAbs, uint256(uUNIT), yAbs);
138138
if (resultAbs > uint256(uMAX_SD59x18)) {
139139
revert Errors.PRBMath_SD59x18_Div_Overflow(x, y);
@@ -143,7 +143,7 @@ function div(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
143143
// negative, 0 for positive or zero).
144144
bool sameSign = (xInt ^ yInt) > -1;
145145

146-
// If the inputs don't have the same sign, the result should be negative. Otherwise, it should be positive.
146+
// If the inputs have the same sign, the result should be positive. Otherwise, it should be negative.
147147
unchecked {
148148
result = wrap(sameSign ? int256(resultAbs) : -int256(resultAbs));
149149
}
@@ -156,10 +156,10 @@ function div(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
156156
/// $$
157157
///
158158
/// @dev Notes:
159-
/// - All from {exp2}.
159+
/// - Refer to the notes in {exp2}.
160160
///
161161
/// Requirements:
162-
/// - All from {exp2}.
162+
/// - Refer to the requirements in {exp2}.
163163
/// - x must be less than 133_084258667509499441.
164164
///
165165
/// @param x The exponent as an SD59x18 number.
@@ -273,7 +273,7 @@ function frac(SD59x18 x) pure returns (SD59x18 result) {
273273
/// - The result is rounded toward zero.
274274
///
275275
/// Requirements:
276-
/// - x * y must fit in SD59x18, otherwise the result overflows.
276+
/// - x * y must fit in SD59x18.
277277
/// - x * y must not be negative, since complex numbers are not supported.
278278
///
279279
/// @param x The first operand as an SD59x18 number.
@@ -299,7 +299,7 @@ function gm(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
299299
revert Errors.PRBMath_SD59x18_Gm_NegativeProduct(x, y);
300300
}
301301

302-
// We don't need to multiply the result by `UNIT` here because the x*y product had picked up a factor of `UNIT`
302+
// We don't need to multiply the result by `UNIT` here because the x*y product picked up a factor of `UNIT`
303303
// during multiplication. See the comments in {Common.sqrt}.
304304
uint256 resultUint = Common.sqrt(uint256(xyInt));
305305
result = wrap(int256(resultUint));
@@ -328,11 +328,11 @@ function inv(SD59x18 x) pure returns (SD59x18 result) {
328328
/// $$
329329
///
330330
/// @dev Notes:
331-
/// - All from {log2}.
331+
/// - Refer to the notes in {log2}.
332332
/// - The precision isn't sufficiently fine-grained to return exactly `UNIT` when the input is `E`.
333333
///
334334
/// Requirements:
335-
/// - All from {log2}.
335+
/// - Refer to the requirements in {log2}.
336336
///
337337
/// @param x The SD59x18 number for which to calculate the natural logarithm.
338338
/// @return result The natural logarithm as an SD59x18 number.
@@ -352,10 +352,10 @@ function ln(SD59x18 x) pure returns (SD59x18 result) {
352352
/// However, if x is an exact power of ten, a hard coded value is returned.
353353
///
354354
/// @dev Notes:
355-
/// - All from {log2}.
355+
/// - Refer to the notes in {log2}.
356356
///
357357
/// Requirements:
358-
/// - All from {log2}.
358+
/// - Refer to the requirements in {log2}.
359359
///
360360
/// @param x The SD59x18 number for which to calculate the common logarithm.
361361
/// @return result The common logarithm as an SD59x18 number.
@@ -460,7 +460,7 @@ function log10(SD59x18 x) pure returns (SD59x18 result) {
460460

461461
/// @notice Calculates the binary logarithm of x using the iterative approximation algorithm.
462462
///
463-
/// For $0 \leq x < 1$, the logarithm is calculated as:
463+
/// For $0 \leq x \lt 1$, the logarithm is calculated as:
464464
///
465465
/// $$
466466
/// log_2{x} = -log_2{\frac{1}{x}}
@@ -531,11 +531,10 @@ function log2(SD59x18 x) pure returns (SD59x18 result) {
531531
/// @notice Multiplies two SD59x18 numbers together, returning a new SD59x18 number.
532532
///
533533
/// @dev Notes:
534-
/// - All from {Common.mulDiv18}.
535-
/// - The result is rounded toward zero.
534+
/// - Refer to the notes in {Common.mulDiv18}.
536535
///
537536
/// Requirements:
538-
/// - All from {Common.mulDiv18}.
537+
/// - Refer to the requirements in {Common.mulDiv18}.
539538
/// - None of the inputs can be `MIN_SD59x18`.
540539
/// - The result must fit in SD59x18.
541540
///
@@ -558,6 +557,7 @@ function mul(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
558557
yAbs = yInt < 0 ? uint256(-yInt) : uint256(yInt);
559558
}
560559

560+
// Compute the absolute value (x*y÷UNIT). The resulting value must fit in SD59x18.
561561
uint256 resultAbs = Common.mulDiv18(xAbs, yAbs);
562562
if (resultAbs > uint256(uMAX_SD59x18)) {
563563
revert Errors.PRBMath_SD59x18_Mul_Overflow(x, y);
@@ -567,7 +567,7 @@ function mul(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
567567
// negative, 0 for positive or zero).
568568
bool sameSign = (xInt ^ yInt) > -1;
569569

570-
// If the inputs have the same sign, the result should be negative. Otherwise, it should be positive.
570+
// If the inputs have the same sign, the result should be positive. Otherwise, it should be negative.
571571
unchecked {
572572
result = wrap(sameSign ? int256(resultAbs) : -int256(resultAbs));
573573
}
@@ -580,11 +580,11 @@ function mul(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
580580
/// $$
581581
///
582582
/// @dev Notes:
583-
/// - All from {exp2}, {log2}, and {mul}.
583+
/// - Refer to the notes in {exp2}, {log2}, and {mul}.
584584
/// - Returns `UNIT` for 0^0.
585585
///
586586
/// Requirements:
587-
/// - All from {exp2}, {log2}, and {mul}.
587+
/// - Refer to the requirements in {exp2}, {log2}, and {mul}.
588588
///
589589
/// @param x The base as an SD59x18 number.
590590
/// @param y Exponent to raise x to, as an SD59x18 number
@@ -622,11 +622,11 @@ function pow(SD59x18 x, SD59x18 y) pure returns (SD59x18 result) {
622622
/// @dev See https://en.wikipedia.org/wiki/Exponentiation_by_squaring.
623623
///
624624
/// Notes:
625-
/// - All from {Common.mulDiv18}.
625+
/// - Refer to the notes in {Common.mulDiv18}.
626626
/// - Returns `UNIT` for 0^0.
627627
///
628628
/// Requirements:
629-
/// - All from {abs} and {Common.mulDiv18}.
629+
/// - Refer to the requirements in {abs} and {Common.mulDiv18}.
630630
/// - The result must fit in SD59x18.
631631
///
632632
/// @param x The base as an SD59x18 number.
@@ -656,7 +656,7 @@ function powu(SD59x18 x, uint256 y) pure returns (SD59x18 result) {
656656
}
657657

658658
unchecked {
659-
// Is the base negative and the exponent odd? If yes, the result is negative.
659+
// Is the base negative and the exponent odd? If yes, the result should be negative.
660660
int256 resultInt = int256(resultAbs);
661661
bool isNegative = x.unwrap() < 0 && y & 1 == 1;
662662
if (isNegative) {

‎src/ud60x18/Constants.sol‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,11 @@ UD60x18 constant EXP2_MAX_INPUT = UD60x18.wrap(uEXP2_MAX_INPUT);
2020
uint256 constant uHALF_UNIT = 0.5e18;
2121
UD60x18 constant HALF_UNIT = UD60x18.wrap(uHALF_UNIT);
2222

23-
/// @dev $log2(10)$ as a UD60x18 number.
23+
/// @dev $log_2(10)$ as a UD60x18 number.
2424
uint256 constant uLOG2_10 = 3_321928094887362347;
2525
UD60x18 constant LOG2_10 = UD60x18.wrap(uLOG2_10);
2626

27-
/// @dev $log2(e)$ as a UD60x18 number.
27+
/// @dev $log_2(e)$ as a UD60x18 number.
2828
uint256 constant uLOG2_E = 1_442695040888963407;
2929
UD60x18 constant LOG2_E = UD60x18.wrap(uLOG2_E);
3030

‎src/ud60x18/Math.sol‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -87,11 +87,10 @@ function ceil(UD60x18 x) pure returns (UD60x18 result) {
8787
/// @dev Uses {Common.mulDiv} to enable overflow-safe multiplication and division.
8888
///
8989
/// Notes:
90-
/// - The result is rounded down.
90+
/// - Refer to the notes in {Common.mulDiv}.
9191
///
9292
/// Requirements:
93-
/// - The denominator must not be zero.
94-
/// - All from {Common.mulDiv}.
93+
/// - Refer to the requirements in {Common.mulDiv}.
9594
///
9695
/// @param x The numerator as a UD60x18 number.
9796
/// @param y The denominator as a UD60x18 number.
@@ -184,7 +183,7 @@ function frac(UD60x18 x) pure returns (UD60x18 result) {
184183
/// @notice Calculates the geometric mean of x and y, i.e. $\sqrt{x * y}$, rounding down.
185184
///
186185
/// @dev Requirements:
187-
/// - x * y must fit in UD60x18, otherwise the result overflows.
186+
/// - x * y must fit in UD60x18.
188187
///
189188
/// @param x The first operand as a UD60x18 number.
190189
/// @param y The second operand as a UD60x18 number.
@@ -204,7 +203,7 @@ function gm(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
204203
revert Errors.PRBMath_UD60x18_Gm_Overflow(x, y);
205204
}
206205

207-
// We don't need to multiply the result by `UNIT` here because the x*y product had picked up a factor of `UNIT`
206+
// We don't need to multiply the result by `UNIT` here because the x*y product picked up a factor of `UNIT`
208207
// during multiplication. See the comments in {Common.sqrt}.
209208
result = wrap(Common.sqrt(xyUint));
210209
}
@@ -234,11 +233,11 @@ function inv(UD60x18 x) pure returns (UD60x18 result) {
234233
/// $$
235234
///
236235
/// @dev Notes:
237-
/// - All from {log2}.
236+
/// - Refer to the notes in {log2}.
238237
/// - The precision isn't sufficiently fine-grained to return exactly `UNIT` when the input is `E`.
239-
238+
///
240239
/// Requirements:
241-
/// - All from {log2}.
240+
/// - Refer to the requirements in {log2}.
242241
///
243242
/// @param x The UD60x18 number for which to calculate the natural logarithm.
244243
/// @return result The natural logarithm as a UD60x18 number.
@@ -260,10 +259,10 @@ function ln(UD60x18 x) pure returns (UD60x18 result) {
260259
/// However, if x is an exact power of ten, a hard coded value is returned.
261260
///
262261
/// @dev Notes:
263-
/// - All from {log2}.
262+
/// - Refer to the notes in {log2}.
264263
///
265264
/// Requirements:
266-
/// - All from {log2}.
265+
/// - Refer to the requirements in {log2}.
267266
///
268267
/// @param x The UD60x18 number for which to calculate the common logarithm.
269268
/// @return result The common logarithm as a UD60x18 number.
@@ -433,10 +432,10 @@ function log2(UD60x18 x) pure returns (UD60x18 result) {
433432
/// @dev Uses {Common.mulDiv} to enable overflow-safe multiplication and division.
434433
///
435434
/// Notes:
436-
/// - The result is rounded down.
435+
/// - Refer to the notes in {Common.mulDiv}.
437436
///
438437
/// Requirements:
439-
/// - All from {Common.mulDiv}.
438+
/// - Refer to the requirements in {Common.mulDiv}.
440439
///
441440
/// @dev See the documentation in {Common.mulDiv18}.
442441
/// @param x The multiplicand as a UD60x18 number.
@@ -455,7 +454,7 @@ function mul(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
455454
/// x^y = 2^{log_2{x} * y}
456455
/// $$
457456
///
458-
/// For $0 \leq x < 1$, since the unsigned {log2} is undefined, an equivalent formula is used:
457+
/// For $0 \leq x \lt 1$, since the unsigned {log2} is undefined, an equivalent formula is used:
459458
///
460459
/// $$
461460
/// i = \frac{1}{x}
@@ -464,12 +463,12 @@ function mul(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
464463
/// $$
465464
///
466465
/// @dev Notes:
467-
/// - All from {log2} and {mul}.
466+
/// - Refer to the notes in {log2} and {mul}.
468467
/// - Returns `UNIT` for 0^0.
469468
/// - It may not perform well with very small values of x. Consider using SD59x18 as an alternative.
470469
///
471470
/// Requirements:
472-
/// - All from {exp2}, {log2}, and {mul}.
471+
/// - Refer to the requirements in {exp2}, {log2}, and {mul}.
473472
///
474473
/// @param x The base as a UD60x18 number.
475474
/// @param y The exponent as a UD60x18 number.
@@ -515,7 +514,7 @@ function pow(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
515514
/// @dev See https://en.wikipedia.org/wiki/Exponentiation_by_squaring.
516515
///
517516
/// Notes:
518-
/// - All from {Common.mulDiv18}.
517+
/// - Refer to the notes in {Common.mulDiv18}.
519518
/// - Returns `UNIT` for 0^0.
520519
///
521520
/// Requirements:

0 commit comments

Comments
 (0)