From 8ed4ab5ac4cc86adb82189d0e3f2d20983b0c92e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Fri, 4 Sep 2020 11:45:16 +0200
Subject: [PATCH] doc: format exponents better

The `2^n` notation is common in mathematics, but even then it often
requires parentheses or braces. In JavaScript and C++, the `^` operator
stands for bitwise xor, and should be avoided in the docs. In code tags,
the JavaScript operator `**` can be used. Otherwise, the `sup` tag can
be used for formatting.

PR-URL: https://github.com/nodejs/node/pull/35050
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
---
 doc/api/buffer.md | 4 ++--
 doc/api/crypto.md | 2 +-
 doc/api/n-api.md  | 9 +++++----
 3 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index a80f30a1ad6977..bc6aa20b3bc114 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -3113,8 +3113,8 @@ added: v8.2.0
 
 * {integer} The largest size allowed for a single `Buffer` instance.
 
-On 32-bit architectures, this value currently is `(2^30)-1` (~1GB).
-On 64-bit architectures, this value currently is `(2^31)-1` (~2GB).
+On 32-bit architectures, this value currently is 2<sup>30</sup> - 1 (~1GB).
+On 64-bit architectures, this value currently is 2<sup>31</sup> - 1 (~2GB).
 
 This value is also available as [`buffer.kMaxLength`][].
 
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index f187f7217783ea..25d015d8bdbbb4 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -2783,7 +2783,7 @@ added: REPLACEME
 Return a random integer `n` such that `min <= n < max`.  This
 implementation avoids [modulo bias][].
 
-The range (`max - min`) must be less than `2^48`. `min` and `max` must
+The range (`max - min`) must be less than 2<sup>48</sup>. `min` and `max` must
 be safe integers.
 
 If the `callback` function is not provided, the random integer is
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index f529a07d4a76d1..ee48f47c808efd 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -2315,8 +2315,8 @@ This API is used to convert from the C `int64_t` type to the JavaScript
 The JavaScript `Number` type is described in [Section 6.1.6][]
 of the ECMAScript Language Specification. Note the complete range of `int64_t`
 cannot be represented with full precision in JavaScript. Integer values
-outside the range of [`Number.MIN_SAFE_INTEGER`][] `-(2^53 - 1)` -
-[`Number.MAX_SAFE_INTEGER`][] `(2^53 - 1)` will lose precision.
+outside the range of [`Number.MIN_SAFE_INTEGER`][] `-(2**53 - 1)` -
+[`Number.MAX_SAFE_INTEGER`][] `(2**53 - 1)` will lose precision.
 
 #### napi_create_double
 <!-- YAML
@@ -2860,7 +2860,7 @@ of the given JavaScript `Number`.
 
 If the number exceeds the range of the 32 bit integer, then the result is
 truncated to the equivalent of the bottom 32 bits. This can result in a large
-positive number becoming a negative number if the value is > 2^31 -1.
+positive number becoming a negative number if the value is > 2<sup>31</sup> - 1.
 
 Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the
 result to zero.
@@ -2889,7 +2889,8 @@ This API returns the C `int64` primitive equivalent of the given JavaScript
 `Number`.
 
 `Number` values outside the range of [`Number.MIN_SAFE_INTEGER`][]
-`-(2^53 - 1)` - [`Number.MAX_SAFE_INTEGER`][] `(2^53 - 1)` will lose precision.
+`-(2**53 - 1)` - [`Number.MAX_SAFE_INTEGER`][] `(2**53 - 1)` will lose
+precision.
 
 Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the
 result to zero.