From 366f379076347e24d83d01b2af6b06af7f1c50a5 Mon Sep 17 00:00:00 2001
From: Hugohong258 <282228220+Hugohong258@users.noreply.github.com>
Date: Sun, 20 Sep 2026 01:25:19 +0800
Subject: [PATCH 1/2] docs: clarify row layout of 2D matrices

---
 docs/datatypes/matrices.md          | 14 +++++++-------
 src/function/arithmetic/multiply.js |  3 ++-
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/datatypes/matrices.md b/docs/datatypes/matrices.md
index 01178f7413..055343f3c3 100644
--- a/docs/datatypes/matrices.md
+++ b/docs/datatypes/matrices.md
@@ -209,10 +209,11 @@ const c = [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
 math.size(c)                                  // Array, [2, 2, 3]
 ```
 
-Note that the dimensions themselves do not have a meaning attached. 
-When creating and printing a two-dimensional matrix, the first dimension is 
-normally rendered as the _column_, and the second dimension is rendered as 
-the _row_. For example:
+Dimensions have no inherent meaning for a multidimensional matrix. For a
+two-dimensional array or matrix, however, each top-level element is a **row**:
+the first size entry counts rows, and the second counts columns. For example,
+`[[0, 1, 2], [3, 4, 5]]` has two rows and three columns. Matrix multiplication
+uses this layout, so `math.multiply(a, b)` computes the product `a * b`.
 
 ```js
 console.table(math.zeros([2, 4]))
@@ -220,9 +221,8 @@ console.table(math.zeros([2, 4]))
 // 0 0 0 0
 ```
 
-If you have a matrix where the first dimension means `x` and the second 
-means `y`, this will look confusing since `x` is printed as _column_ 
-(vertically) and `y` as _row_ (horizontally).
+If the first dimension represents `x` and the second represents `y` in your
+data, `x` will appear vertically and `y` horizontally when printed.
 
 
 ## Resizing
diff --git a/src/function/arithmetic/multiply.js b/src/function/arithmetic/multiply.js
index 07e1553b83..cb6a2ab0d0 100644
--- a/src/function/arithmetic/multiply.js
+++ b/src/function/arithmetic/multiply.js
@@ -761,7 +761,8 @@ export const createMultiply = /* #__PURE__ */ factory(name, dependencies, ({ typ
   }
 
   /**
-   * Multiply two or more values, `x * y`.
+   * Multiply two or more values, `x * y`. In a two-dimensional array or matrix,
+   * each top-level element is a row; matrix multiplication computes `x * y`.
    * For matrices, the matrix product is calculated.
    *
    * Syntax:

From d7f02f5f1a96b68789ebe75a301dc203fbf177d3 Mon Sep 17 00:00:00 2001
From: Hugohong258 <282228220+Hugohong258@users.noreply.github.com>
Date: Thu, 5 Nov 2026 09:23:12 +0900
Subject: [PATCH 2/2] docs: limit matrix layout correction to row and column
 terminology

---
 docs/datatypes/matrices.md          | 14 +++++++-------
 src/function/arithmetic/multiply.js |  3 +--
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/datatypes/matrices.md b/docs/datatypes/matrices.md
index 055343f3c3..3d6cee857a 100644
--- a/docs/datatypes/matrices.md
+++ b/docs/datatypes/matrices.md
@@ -209,11 +209,10 @@ const c = [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
 math.size(c)                                  // Array, [2, 2, 3]
 ```
 
-Dimensions have no inherent meaning for a multidimensional matrix. For a
-two-dimensional array or matrix, however, each top-level element is a **row**:
-the first size entry counts rows, and the second counts columns. For example,
-`[[0, 1, 2], [3, 4, 5]]` has two rows and three columns. Matrix multiplication
-uses this layout, so `math.multiply(a, b)` computes the product `a * b`.
+Note that the dimensions themselves do not have a meaning attached.
+When creating and printing a two-dimensional matrix, the first dimension is
+normally rendered as the _row_, and the second dimension is rendered as
+the _column_. For example:
 
 ```js
 console.table(math.zeros([2, 4]))
@@ -221,8 +220,9 @@ console.table(math.zeros([2, 4]))
 // 0 0 0 0
 ```
 
-If the first dimension represents `x` and the second represents `y` in your
-data, `x` will appear vertically and `y` horizontally when printed.
+If you have a matrix where the first dimension means `x` and the second
+means `y`, this will look confusing since `x` is printed as _column_
+(vertically) and `y` as _row_ (horizontally).
 
 
 ## Resizing
diff --git a/src/function/arithmetic/multiply.js b/src/function/arithmetic/multiply.js
index cb6a2ab0d0..07e1553b83 100644
--- a/src/function/arithmetic/multiply.js
+++ b/src/function/arithmetic/multiply.js
@@ -761,8 +761,7 @@ export const createMultiply = /* #__PURE__ */ factory(name, dependencies, ({ typ
   }
 
   /**
-   * Multiply two or more values, `x * y`. In a two-dimensional array or matrix,
-   * each top-level element is a row; matrix multiplication computes `x * y`.
+   * Multiply two or more values, `x * y`.
    * For matrices, the matrix product is calculated.
    *
    * Syntax: