From 699fae1f2cb6d460cf85dca712dd936194b27ce1 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 fbeec94a16a2d8..3025b285883380 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -3137,8 +3137,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 f0c7620c10dbcf..e12dd28a33019b 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -2813,7 +2813,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 b3a2f91f9d4895..dc01d79ba9e849 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -2385,8 +2385,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
@@ -2932,7 +2932,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.
@@ -2961,7 +2961,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.