commit 06d845a483030377bf2d2479f88974809f9a87bf
parent 6b7ce7385c6260292c5f241d189b302439b2aff0
Author: Jack Mordaunt <jackmordaunt.dev@gmail.com>
Date: Fri, 18 Sep 2026 16:09:28 -0400
all: keep doc comments to what the code does
Several comments argued for the code against alternatives it does not use, or
recorded what a change replaced. That rationale belongs in the commit that
made the change, where it stays accurate; in a doc comment it reads as review
notes and goes stale.
Diffstat:
6 files changed, 10 insertions(+), 20 deletions(-)
diff --git a/cmd/icnsify/doc.go b/cmd/icnsify/doc.go
@@ -9,8 +9,8 @@ import (
// version is stamped by goreleaser at build time.
var version = "master"
-// option records a flag registered under a long and a short name so usage
-// can list each one once, GNU style, instead of twice as PrintDefaults would.
+// option records a flag registered under both a long and a short name, so
+// usage can list the pair once, GNU style.
type option struct {
long, short string
def, usage string
diff --git a/cmd/icnsify/pipe.go b/cmd/icnsify/pipe.go
@@ -6,9 +6,7 @@ import (
)
// stdinIsPipe reports whether stdin is a pipe or redirected file rather than
-// an interactive terminal. It deliberately ignores the stream's current size:
-// a producer such as `cat icon.png | icnsify` may not have written anything
-// by the time we look, and a zero size would wrongly read as "no input".
+// an interactive terminal.
func stdinIsPipe() (bool, error) {
info, err := os.Stdin.Stat()
if err != nil {
diff --git a/cmd/shell-extension/internal/provider/provider.go b/cmd/shell-extension/internal/provider/provider.go
@@ -226,8 +226,7 @@ func Thumbnail(r io.Reader, cx int) (*image.RGBA, error) {
if w == b.Dx() && h == b.Dy() {
draw.Draw(rgba, rgba.Bounds(), chosen, b.Min, draw.Src)
} else {
- // CatmullRom is x/image's high quality kernel, and rings less on the
- // hard edges typical of icons than a wider Lanczos window.
+ // CatmullRom is x/image's high quality kernel.
draw.CatmullRom.Scale(rgba, rgba.Bounds(), chosen, b, draw.Src, nil)
}
return rgba, nil
diff --git a/icns.go b/icns.go
@@ -94,12 +94,10 @@ func NewIconSet(img image.Image, interp InterpolationFunction) (*IconSet, error)
}
// resizeSquare scales img into a size by size square, ignoring the source
-// aspect ratio. An image already at that size is passed through untouched,
-// which keeps the largest icon identical to the source and skips the most
-// expensive resample in the common case.
+// aspect ratio. An image already that size is returned as it is.
//
-// Scaling happens in alpha-premultiplied space, which is what keeps colour
-// from bleeding out of fully transparent pixels into the icon's edges.
+// Scaling happens in alpha-premultiplied space, so colour does not bleed out
+// of fully transparent pixels into the icon's edges.
func resizeSquare(img image.Image, size uint, scaler draw.Interpolator) image.Image {
bounds := img.Bounds()
if bounds.Dx() == int(size) && bounds.Dy() == int(size) {
@@ -140,8 +138,7 @@ func findNearestSize(img image.Image) uint {
return 0
}
-// biggestSide returns the larger dimension of img. Bounds need not start at
-// the origin, so measure the rectangle rather than its far corner.
+// biggestSide returns the larger of img's two dimensions.
func biggestSide(img image.Image) uint {
b := img.Bounds()
return uint(max(b.Dx(), b.Dy(), 0))
diff --git a/interpolation.go b/interpolation.go
@@ -7,10 +7,6 @@ import (
)
// InterpolationFunction is the algorithm used to resize the image.
-//
-// It is an enumeration of this package's own rather than an alias for the
-// resampling library's type, so the resampler can be replaced without
-// breaking callers.
type InterpolationFunction int
// InterpolationFunction constants, ordered from fastest to highest quality.
diff --git a/reader.go b/reader.go
@@ -87,8 +87,8 @@ const elementHeaderSize = 8
// An icns file is a sequence of elements, each a 4-byte type followed by a
// 4-byte big-endian length that counts the whole element, header included.
// The file itself is one such element of type "icns" enclosing the rest.
-// Every length is validated against the data actually present so malformed
-// or truncated input yields an error rather than a panic or an endless loop.
+// Every length is checked against the data present, and input that disagrees
+// is reported as ErrMalformed.
func decode(r io.Reader) (icons []iconReader, err error) {
data, err := io.ReadAll(r)
if err != nil {
