all: fix doc comments identified by staticcheck

All complaints in mathext/internal are ignored, and an unfortunate naming
of methods in spatial/{r2,r3} is now permanent.

dsp/window/window_complex.go

@@ -6,8 +6,8 @@ package window
 
 import "math"
 
-// Rectangular modifies seq in place by the Rectangular window and returns
+// RectangularComplex modifies seq in place by the Rectangular window and
-// the result.
+// returns the result.
 // See https://en.wikipedia.org/wiki/Window_function#Rectangular_window and
 // https://www.recordingblogs.com/wiki/rectangular-window for details.
 //

floats/floats.go

@@ -633,9 +633,9 @@ func Prod(s []float64) float64 {
 	return prod
 }
 
-// Deprecated: This function simply calls [slices.Reverse].
-//
 // Reverse reverses the order of elements in the slice.
+//
+// Deprecated: This function simply calls [slices.Reverse].
 func Reverse(s []float64) {
 	slices.Reverse(s)
 }

graph/formats/dot/internal/errors/doc.go

@@ -2,5 +2,5 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package error provides generated internal error functions for DOT parsing.
+// Package errors provides generated internal error functions for DOT parsing.
 package errors // import "gonum.org/v1/gonum/graph/formats/dot/internal/errors"

graph/path/internal/testgraphs/doc.go

@@ -2,6 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package testsgraphs provides a number of graphs used for testing
+// Package testgraphs provides a number of graphs used for testing
 // routines in the path and path/dynamic packages.
 package testgraphs // import "gonum.org/v1/gonum/graph/path/internal/testgraphs"

integrate/quad/quad.go

@@ -18,9 +18,11 @@ type FixedLocationer interface {
 	FixedLocations(x, weight []float64, min, max float64)
 }
 
-// FixedLocationSingle returns the location and weight for element k in a
+// FixedLocationSingler wraps the FixedLocationSingle method.
-// fixed quadrature rule with n total samples and integral bounds from min to max.
 type FixedLocationSingler interface {
+	// FixedLocationSingle returns the location and weight for
+	// element k in a fixed quadrature rule with n total samples
+	// and integral bounds from min to max.
 	FixedLocationSingle(n, k int, min, max float64) (x, weight float64)
 }
 

lapack/lapack.go

@@ -221,7 +221,7 @@ const (
 	EVSelected EVHowMany = 'S' // Compute selected right and/or left eigenvectors.
 )
 
-// MaximizeNormX specifies the heuristic method for computing a contribution to
+// MaximizeNormXJob specifies the heuristic method for computing a contribution to
 // the reciprocal Dif-estimate in Dlatdf.
 type MaximizeNormXJob byte
 

lapack/testlapack/dgesc2.go

@@ -1,6 +1,7 @@
 // Copyright ©2021 The Gonum Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
+
 package testlapack
 
 import (

mat/lu.go

@@ -237,6 +237,8 @@ func (lu *LU) RowPivots(dst []int) []int {
 	return dst
 }
 
+// Pivot returns the row pivots of the receiver.
+//
 // Deprecated: Use RowPivots instead.
 func (lu *LU) Pivot(dst []int) []int {
 	return lu.RowPivots(dst)

optimize/convex/lp/simplex.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// package lp implements routines for solving linear programs.
+// Package lp implements routines for solving linear programs.
 package lp
 
 import (

spatial/r2/box.go

@@ -31,7 +31,7 @@ func (a Box) Center() Vec {
 	return Scale(0.5, Add(a.Min, a.Max))
 }
 
-// IsEmpty returns true if a Box's volume is zero
+// Empty returns true if a Box's volume is zero
 // or if a Min component is greater than its Max component.
 func (a Box) Empty() bool {
 	return a.Min.X >= a.Max.X || a.Min.Y >= a.Max.Y

spatial/r3/box.go

@@ -21,7 +21,7 @@ func NewBox(x0, y0, z0, x1, y1, z1 float64) Box {
 	}
 }
 
-// IsEmpty returns true if a Box's volume is zero
+// Empty returns true if a Box's volume is zero
 // or if a Min component is greater than its Max component.
 func (a Box) Empty() bool {
 	return a.Min.X >= a.Max.X || a.Min.Y >= a.Max.Y || a.Min.Z >= a.Max.Z