simd/archsimd: adjust documentations slightly

- Reword the documentation of Scale to mention parameter names.
- Correct the parameter name in Merge.
- Use proper a/an articles in some documentation.
- Add punctuations.
- Format code blocks for long expressions.

Change-Id: I8a31721503c1b155862255619a835895f3d5123a
Reviewed-on: https://go-review.googlesource.com/c/go/+/731560
Reviewed-by: David Chase <drchase@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

5 files changed, 68 insertions, 51 deletions

diff --git a/src/simd/archsimd/_gen/simdgen/gen_simdTypes.go b/src/simd/archsimd/_gen/simdgen/gen_simdTypes.go
index baf035f31d..453784ff36 100644
--- a/src/simd/archsimd/_gen/simdgen/gen_simdTypes.go
+++ b/src/simd/archsimd/_gen/simdgen/gen_simdTypes.go
@@ -142,7 +142,7 @@ type v{{.}} struct {
 {{end}}
 
 {{define "typeTmpl"}}
-// {{.Name}} is a {{.Size}}-bit SIMD vector of {{.Lanes}} {{.Base}}
+// {{.Name}} is a {{.Size}}-bit SIMD vector of {{.Lanes}} {{.Base}}s.
 type {{.Name}} struct {
 {{.Fields}}
 }
@@ -178,15 +178,15 @@ func (X86Features) {{.Feature}}() bool {
 `
 
 const simdLoadStoreTemplate = `
-// Len returns the number of elements in a {{.Name}}
+// Len returns the number of elements in {{.Article}} {{.Name}}.
 func (x {{.Name}}) Len() int { return {{.Lanes}} }
 
-// Load{{.Name}} loads a {{.Name}} from an array
+// Load{{.Name}} loads {{.Article}} {{.Name}} from an array.
 //
 //go:noescape
 func Load{{.Name}}(y *[{{.Lanes}}]{{.Base}}) {{.Name}}
 
-// Store stores a {{.Name}} to an array
+// Store stores {{.Article}} {{.Name}} to an array.
 //
 //go:noescape
 func (x {{.Name}}) Store(y *[{{.Lanes}}]{{.Base}})
@@ -211,16 +211,16 @@ func (x {{.Name}}) ToBits() uint{{.LanesContainer}}
 `
 
 const simdMaskedLoadStoreTemplate = `
-// LoadMasked{{.Name}} loads a {{.Name}} from an array,
-// at those elements enabled by mask
+// LoadMasked{{.Name}} loads {{.Article}} {{.Name}} from an array,
+// at those elements enabled by mask.
 //
 {{.MaskedLoadDoc}}
 //
 //go:noescape
 func LoadMasked{{.Name}}(y *[{{.Lanes}}]{{.Base}}, mask Mask{{.ElemBits}}x{{.Lanes}}) {{.Name}}
 
-// StoreMasked stores a {{.Name}} to an array,
-// at those elements enabled by mask
+// StoreMasked stores {{.Article}} {{.Name}} to an array,
+// at those elements enabled by mask.
 //
 {{.MaskedStoreDoc}}
 //
@@ -407,10 +407,10 @@ func (x {{.Tsrc.Name}}) As{{.Tdst.Name}}() {{.Tdst.Name}}
 {{end}}
 
 {{define "mask"}}
-// To{{.VectorCounterpart}} converts from {{.Name}} to {{.VectorCounterpart}}
+// To{{.VectorCounterpart}} converts from {{.Name}} to {{.VectorCounterpart}}.
 func (from {{.Name}}) To{{.VectorCounterpart}}() (to {{.VectorCounterpart}})
 
-// asMask converts from {{.VectorCounterpart}} to {{.Name}}
+// asMask converts from {{.VectorCounterpart}} to {{.Name}}.
 func (from {{.VectorCounterpart}}) asMask() (to {{.Name}})
 
 func (x {{.Name}}) And(y {{.Name}}) {{.Name}}
diff --git a/src/simd/archsimd/_gen/simdgen/ops/FPonlyArith/categories.yaml b/src/simd/archsimd/_gen/simdgen/ops/FPonlyArith/categories.yaml
index a270ca54ab..90f5208ff7 100644
--- a/src/simd/archsimd/_gen/simdgen/ops/FPonlyArith/categories.yaml
+++ b/src/simd/archsimd/_gen/simdgen/ops/FPonlyArith/categories.yaml
@@ -18,7 +18,8 @@
 - go: Scale
   commutative: false
   documentation: !string |-
-    // NAME multiplies elements by a power of 2.
+    // NAME multiplies each element of x by 2 raised to the power of the
+    // floor of the corresponding element in y.
 - go: RoundToEven
   commutative: false
   constImm: 0
diff --git a/src/simd/archsimd/_gen/simdgen/ops/Moves/categories.yaml b/src/simd/archsimd/_gen/simdgen/ops/Moves/categories.yaml
index 9e945cdebd..38bc9374cc 100644
--- a/src/simd/archsimd/_gen/simdgen/ops/Moves/categories.yaml
+++ b/src/simd/archsimd/_gen/simdgen/ops/Moves/categories.yaml
@@ -31,17 +31,23 @@
   commutative: false
   documentation: !string |-
     // NAME performs a full permutation of vector x using indices:
-    // result := {x[indices[0]], x[indices[1]], ..., x[indices[n]]}
+    //
+    //   result = {x[indices[0]], x[indices[1]], ..., x[indices[n]]}
+    //
 - go: Permute
   commutative: false
   documentation: !string |-
     // NAME performs a full permutation of vector x using indices:
-    // result := {x[indices[0]], x[indices[1]], ..., x[indices[n]]}
+    //
+    //   result = {x[indices[0]], x[indices[1]], ..., x[indices[n]]}
+    //
 - go: ConcatPermute # ConcatPermute is only available on or after AVX512
   commutative: false
   documentation: !string |-
     // NAME performs a full permutation of vector x, y using indices:
-    // result := {xy[indices[0]], xy[indices[1]], ..., xy[indices[n]]}
+    //
+    //   result = {xy[indices[0]], xy[indices[1]], ..., xy[indices[n]]}
+    //
     // where xy is the concatenation of x (lower half) and y (upper half).
     // Only the needed bits to represent xy's index are used in indices' elements.
 - go: Compress
diff --git a/src/simd/archsimd/_gen/simdgen/ops/Moves/go.yaml b/src/simd/archsimd/_gen/simdgen/ops/Moves/go.yaml
index d3aa7d4cdc..e1fd184ed7 100644
--- a/src/simd/archsimd/_gen/simdgen/ops/Moves/go.yaml
+++ b/src/simd/archsimd/_gen/simdgen/ops/Moves/go.yaml
@@ -227,7 +227,7 @@
 - go: Permute
   asm: "VPERMQ|VPERMPD"
   addDoc: !string |-
-    // The low 2 bits (values 0-3) of each element of indices is used
+    // The low 2 bits (values 0-3) of each element of indices is used.
   operandOrder: "21Type1"
   in:
   - &anyindices
@@ -244,7 +244,7 @@
 - go: Permute
   asm: "VPERM[WDQ]|VPERMP[SD]"
   addDoc: !string |-
-    // The low 3 bits (values 0-7) of each element of indices is used
+    // The low 3 bits (values 0-7) of each element of indices is used.
   operandOrder: "21Type1"
   in:
   - *anyindices
@@ -257,7 +257,7 @@
 - go: Permute
   asm: "VPERM[BWD]|VPERMPS"
   addDoc: !string |-
-    // The low 4 bits (values 0-15) of each element of indices is used
+    // The low 4 bits (values 0-15) of each element of indices is used.
   operandOrder: "21Type1"
   in:
   - *anyindices
@@ -270,7 +270,7 @@
 - go: Permute
   asm: "VPERM[BW]"
   addDoc: !string |-
-    // The low 5 bits (values 0-31) of each element of indices is used
+    // The low 5 bits (values 0-31) of each element of indices is used.
   operandOrder: "21Type1"
   in:
   - *anyindices
@@ -283,7 +283,7 @@
 - go: Permute
   asm: "VPERMB"
   addDoc: !string |-
-    // The low 6 bits (values 0-63) of each element of indices is used
+    // The low 6 bits (values 0-63) of each element of indices is used.
   operandOrder: "21Type1"
   in:
   - *anyindices
@@ -489,7 +489,9 @@
 - go: PermuteOrZeroGrouped
   asm: VPSHUFB
   addDoc: !string |-
-    // result = {x_group0[indices[0]], x_group0[indices[1]], ..., x_group1[indices[16]], x_group1[indices[17]], ...}
+    //
+    //   result = {x_group0[indices[0]], x_group0[indices[1]], ..., x_group1[indices[16]], x_group1[indices[17]], ...}
+    //
     // The lower four bits of each byte-sized index in indices select an element from its corresponding group in x,
     // unless the index's sign bit is set in which case zero is used instead.
     // Each group is of size 128-bit.
@@ -506,7 +508,9 @@
 - go: permuteScalars
   asm: VPSHUFD
   addDoc: !string |-
-    // result = {x[indices[0:2]], x[indices[2:4]], x[indices[4:6]], x[indices[6:8]]}
+    //
+    //   result = {x[indices[0:2]], x[indices[2:4]], x[indices[4:6]], x[indices[6:8]]}
+    //
     // Indices is four 2-bit values packed into a byte, thus indices[0:2] is the first index.
   in:
   - *128any
@@ -520,7 +524,9 @@
 - go: permuteScalarsGrouped
   asm: VPSHUFD
   addDoc: !string |-
-    // result = {x_group0[indices[0:2]], x_group0[indices[2:4]], x_group0[indices[4:6]], x_group0[indices[6:8]], x_group1[indices[0:2]], ...}
+    //
+    //   result = {x_group0[indices[0:2]], x_group0[indices[2:4]], x_group0[indices[4:6]], x_group0[indices[6:8]], x_group1[indices[0:2]], ...}
+    //
     // Indices is four 2-bit values packed into a byte, thus indices[0:2] is the first index.
     // Each group is of size 128-bit.
   in:
@@ -535,7 +541,9 @@
 - go: permuteScalarsLo
   asm: VPSHUFLW
   addDoc: !string |-
-    // result = {x[indices[0:2]], x[indices[2:4]], x[indices[4:6]], x[indices[6:8]], x[4], x[5], x[6], x[7]}
+    //
+    //   result = {x[indices[0:2]], x[indices[2:4]], x[indices[4:6]], x[indices[6:8]], x[4], x[5], x[6], x[7]}
+    //
     // Indices is four 2-bit values packed into a byte, thus indices[0:2] is the first index.
   in:
     - &128lanes8
@@ -573,7 +581,9 @@
 - go: permuteScalarsHi
   asm: VPSHUFHW
   addDoc: !string |-
-    // result = {x[0], x[1], x[2], x[3], x[indices[0:2]+4], x[indices[2:4]+4], x[indices[4:6]+4], x[indices[6:8]+4]}
+    //
+    //   result = {x[0], x[1], x[2], x[3], x[indices[0:2]+4], x[indices[2:4]+4], x[indices[4:6]+4], x[indices[6:8]+4]}
+    //
     // Indices is four 2-bit values packed into a byte, thus indices[0:2] is the first index.
   in:
   - *128lanes8
diff --git a/src/simd/archsimd/_gen/tmplgen/main.go b/src/simd/archsimd/_gen/tmplgen/main.go
index e764bee498..e0d607af12 100644
--- a/src/simd/archsimd/_gen/tmplgen/main.go
+++ b/src/simd/archsimd/_gen/tmplgen/main.go
@@ -323,12 +323,12 @@ func shapedTemplateOf(s *shapes, name, temp string) shapeAndTemplate {
 }
 
 var sliceTemplate = templateOf("slice", `
-// Load{{.VType}}Slice loads {{.AOrAn}} {{.VType}} from a slice of at least {{.Count}} {{.Etype}}s
+// Load{{.VType}}Slice loads {{.AOrAn}} {{.VType}} from a slice of at least {{.Count}} {{.Etype}}s.
 func Load{{.VType}}Slice(s []{{.Etype}}) {{.VType}} {
 	return Load{{.VType}}((*[{{.Count}}]{{.Etype}})(s))
 }
 
-// StoreSlice stores x into a slice of at least {{.Count}} {{.Etype}}s
+// StoreSlice stores x into a slice of at least {{.Count}} {{.Etype}}s.
 func (x {{.VType}}) StoreSlice(s []{{.Etype}}) {
 	x.Store((*[{{.Count}}]{{.Etype}})(s))
 }
@@ -640,32 +640,32 @@ func (t templateData) CPUfeature() string {
 }
 
 var avx2SignedComparisonsTemplate = shapedTemplateOf(avx2SignedComparisons, "avx2 signed comparisons", `
-// Less returns a mask whose elements indicate whether x < y
+// Less returns a mask whose elements indicate whether x < y.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) Less(y {{.VType}}) Mask{{.WxC}} {
 	return y.Greater(x)
 }
 
-// GreaterEqual returns a mask whose elements indicate whether x >= y
+// GreaterEqual returns a mask whose elements indicate whether x >= y.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) GreaterEqual(y {{.VType}}) Mask{{.WxC}} {
 	ones := x.Equal(x).ToInt{{.WxC}}()
 	return y.Greater(x).ToInt{{.WxC}}().Xor(ones).asMask()
 }
 
-// LessEqual returns a mask whose elements indicate whether x <= y
+// LessEqual returns a mask whose elements indicate whether x <= y.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) LessEqual(y {{.VType}}) Mask{{.WxC}} {
 	ones := x.Equal(x).ToInt{{.WxC}}()
 	return x.Greater(y).ToInt{{.WxC}}().Xor(ones).asMask()
 }
 
-// NotEqual returns a mask whose elements indicate whether x != y
+// NotEqual returns a mask whose elements indicate whether x != y.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) NotEqual(y {{.VType}}) Mask{{.WxC}} {
 	ones := x.Equal(x).ToInt{{.WxC}}()
 	return x.Equal(y).ToInt{{.WxC}}().Xor(ones).asMask()	
@@ -673,18 +673,18 @@ func (x {{.VType}}) NotEqual(y {{.VType}}) Mask{{.WxC}} {
 `)
 
 var bitWiseIntTemplate = shapedTemplateOf(intShapes, "bitwise int complement", `
-// Not returns the bitwise complement of x
+// Not returns the bitwise complement of x.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) Not() {{.VType}} {
 	return x.Xor(x.Equal(x).ToInt{{.WxC}}())
 }
 `)
 
 var bitWiseUintTemplate = shapedTemplateOf(uintShapes, "bitwise uint complement", `
-// Not returns the bitwise complement of x
+// Not returns the bitwise complement of x.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) Not() {{.VType}} {
 	return x.Xor(x.Equal(x).ToInt{{.WxC}}().As{{.VType}}())
 }
@@ -703,9 +703,9 @@ func (t templateData) CPUfeatureAVX2if8() string {
 }
 
 var avx2UnsignedComparisonsTemplate = shapedTemplateOf(avx2UnsignedComparisons, "avx2 unsigned comparisons", `
-// Greater returns a mask whose elements indicate whether x > y
+// Greater returns a mask whose elements indicate whether x > y.
 //
-// Emulated, CPU Feature {{.CPUfeatureAVX2if8}}
+// Emulated, CPU Feature: {{.CPUfeatureAVX2if8}}
 func (x {{.VType}}) Greater(y {{.VType}}) Mask{{.WxC}} {
 	a, b := x.AsInt{{.WxC}}(), y.AsInt{{.WxC}}()
 {{- if eq .EWidth 8}}
@@ -717,9 +717,9 @@ func (x {{.VType}}) Greater(y {{.VType}}) Mask{{.WxC}} {
 	return a.Xor(signs).Greater(b.Xor(signs))
 }
 
-// Less returns a mask whose elements indicate whether x < y
+// Less returns a mask whose elements indicate whether x < y.
 //
-// Emulated, CPU Feature {{.CPUfeatureAVX2if8}}
+// Emulated, CPU Feature: {{.CPUfeatureAVX2if8}}
 func (x {{.VType}}) Less(y {{.VType}}) Mask{{.WxC}} {
 	a, b := x.AsInt{{.WxC}}(), y.AsInt{{.WxC}}()
 {{- if eq .EWidth 8}}
@@ -731,9 +731,9 @@ func (x {{.VType}}) Less(y {{.VType}}) Mask{{.WxC}} {
 	return b.Xor(signs).Greater(a.Xor(signs))
 }
 
-// GreaterEqual returns a mask whose elements indicate whether x >= y
+// GreaterEqual returns a mask whose elements indicate whether x >= y.
 //
-// Emulated, CPU Feature {{.CPUfeatureAVX2if8}}
+// Emulated, CPU Feature: {{.CPUfeatureAVX2if8}}
 func (x {{.VType}}) GreaterEqual(y {{.VType}}) Mask{{.WxC}} {
 	a, b := x.AsInt{{.WxC}}(), y.AsInt{{.WxC}}()
 	ones := x.Equal(x).ToInt{{.WxC}}()
@@ -745,9 +745,9 @@ func (x {{.VType}}) GreaterEqual(y {{.VType}}) Mask{{.WxC}} {
 	return b.Xor(signs).Greater(a.Xor(signs)).ToInt{{.WxC}}().Xor(ones).asMask()
 }
 
-// LessEqual returns a mask whose elements indicate whether x <= y
+// LessEqual returns a mask whose elements indicate whether x <= y.
 //
-// Emulated, CPU Feature {{.CPUfeatureAVX2if8}}
+// Emulated, CPU Feature: {{.CPUfeatureAVX2if8}}
 func (x {{.VType}}) LessEqual(y {{.VType}}) Mask{{.WxC}} {
 	a, b := x.AsInt{{.WxC}}(), y.AsInt{{.WxC}}()
 	ones := x.Equal(x).ToInt{{.WxC}}()
@@ -759,9 +759,9 @@ func (x {{.VType}}) LessEqual(y {{.VType}}) Mask{{.WxC}} {
 	return a.Xor(signs).Greater(b.Xor(signs)).ToInt{{.WxC}}().Xor(ones).asMask()
 }
 
-// NotEqual returns a mask whose elements indicate whether x != y
+// NotEqual returns a mask whose elements indicate whether x != y.
 //
-// Emulated, CPU Feature {{.CPUfeature}}
+// Emulated, CPU Feature: {{.CPUfeature}}
 func (x {{.VType}}) NotEqual(y {{.VType}}) Mask{{.WxC}} {
 	a, b := x.AsInt{{.WxC}}(), y.AsInt{{.WxC}}()
 	ones := x.Equal(x).ToInt{{.WxC}}()
@@ -818,7 +818,7 @@ func (x {{.VType}}) Masked(mask Mask{{.WxC}}) {{.VType}} {
 {{- end -}}
 }
 
-// Merge returns x but with elements set to y where m is false.
+// Merge returns x but with elements set to y where mask is false.
 func (x {{.VType}}) Merge(y {{.VType}}, mask Mask{{.WxC}}) {{.VType}} {
 {{- if eq .Base "Int" }}
 	return y.blendMasked(x, mask)
@@ -849,7 +849,7 @@ var broadcastTemplate = templateOf("Broadcast functions", `
 // Broadcast{{.VType}} returns a vector with the input
 // x assigned to all elements of the output.
 //
-// Emulated, CPU Feature {{.CPUfeatureBC}}
+// Emulated, CPU Feature: {{.CPUfeatureBC}}
 func Broadcast{{.VType}}(x {{.Etype}}) {{.VType}} {
 	var z {{.As128BitVec }}
 	return z.SetElem(0, x).Broadcast{{.Vwidth}}()
@@ -864,7 +864,7 @@ func (from {{.Base}}{{.WxC}}) ToMask() (to Mask{{.WxC}}) {
 `)
 
 var stringTemplate = shapedTemplateOf(allShapes, "String methods", `
-// String returns a string representation of SIMD vector x
+// String returns a string representation of SIMD vector x.
 func (x {{.VType}}) String() string {
 	var s [{{.Count}}]{{.Etype}}
 	x.Store(&s)