copyedit: tighten comments and docstrings (Strunk pass)

Apply Elements-of-Style rules to the prose this PR added or modified.
Focus on the heavy-comment files: buildvars package docs, hook
declarations across compose/dgraphtest/t/testutil, hook-call comments
in dgraphtest/local_cluster.go, FIPS-aware skip helpers in
acl/jwt_algo_test.go and check_upgrade/check_upgrade_test.go and
systest/integration2/acl_test.go, plus the misc one-off comments in
dgraph/Makefile, t/Makefile, contrib/Dockerfile, dgraphtest/load.go,
and graphql/e2e/auth/auth_test.go.

Specific changes:
  - Active voice over passive where natural (Rule 10).
  - Positive form over negated (Rule 11): 'are unavailable' for 'isn't
    available', 'lacks' for 'does not have', etc.
  - Concrete over abstract (Rule 12): name the actual value or pattern
    in the example rather than 'various' or 'some'.
  - Drop needless words (Rule 13): cut hedging (essentially, basically,
    typically), pleonasms (actually, really, very), 'in order to' -> 'to',
    'owing to the fact that' -> 'because', and 'is a function which' /
    'is initialized to' constructions.
  - Em-dash discipline: at most one rhetorical em-dash per sentence;
    replace pile-on parentheticals with semicolons or split sentences.
  - Keep technical content unchanged. No code edits, only prose.

17 files; +277/-268 (net +9 from line wrapping).

Author: mlwelles

acl/jwt_algo_test.go

@@ -23,10 +23,11 @@ import (
 )
 
 func TestACLJwtAlgo(t *testing.T) {
-	// EdDSA (Ed25519) is outside Go's FIPS validation boundary; the
+	// EdDSA (Ed25519) lies outside Go's FIPS validation boundary; the
 	// FIPS-restricted dgraph binary rejects it at JWT-signing setup.
-	// Skip the EdDSA iteration when buildvars.FIPSEnabled is true. The remaining algorithms
-	// in jwt.GetAlgorithms() are FIPS-approvable and run in both modes.
+	// Skip the EdDSA iteration when buildvars.FIPSEnabled is true. The
+	// remaining algorithms in jwt.GetAlgorithms() are FIPS-approvable
+	// and run in both modes.
 	fipsBuild := buildvars.FIPSEnabled
 	for _, algo := range jwt.GetAlgorithms() {
 		if algo == "none" || algo == "" {

buildvars/buildvars.go

@@ -3,9 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-// Command buildvars emits the [buildvars] registry as lines of text
-// in a selectable format for consumption by shell eval, GNU Make eval,
-// or direct parsing by a validation script.
+// Command buildvars emits the [buildvars] registry as lines of text in
+// a selectable format for consumption by shell eval, GNU Make eval, or
+// direct parsing by a validation script.
 //
 // Formats:
 //
@@ -25,10 +25,10 @@
 //	validation scripts          — use plain format for diffing against
 //	                              Make-side values
 //
-// Values in shell format are single-quoted with embedded single quotes
-// escaped. Values in make format are emitted raw (newlines and special
-// Make characters in values would break, but all current buildvars values
-// are simple strings).
+// The shell format single-quotes values and escapes embedded single
+// quotes. The make format emits values raw; newlines and special Make
+// characters would break it, but all current buildvars values are
+// simple strings.
 package main
 
 import (
@@ -40,7 +40,7 @@ import (
 	"github.com/dgraph-io/dgraph/v25/buildvars"
 )
 
-// shellQuote wraps s in single quotes, escaping any embedded single
+// shellQuote wraps s in single quotes and escapes any embedded single
 // quotes. Matches POSIX shell conventions for literal string quoting:
 // 'foo'"'"'bar' unambiguously represents foo'bar.
 func shellQuote(s string) string {
@@ -58,7 +58,7 @@ func main() {
 		}
 	case "make":
 		// `:=` rather than `?=` so this command's value overrides any
-		// ambient Make default. Callers that want fallback-only shape
+		// ambient Make default. Callers wanting fallback-only shape
 		// can post-process to replace `:=` with `?=`.
 		for _, v := range buildvars.All {
 			fmt.Fprintf(os.Stdout, "%s := %s\n", v.Name, v.Get())

buildvars/cmd/buildvars/main.go

@@ -6,11 +6,11 @@
 package buildvars
 
 // FIPSEnabled reports whether this binary was built with FIPS 140-3
-// enforcement and is therefore restricted to validated cryptography.
-// Default false. A downstream fork that runs FIPS-enforced builds flips
-// this var to true from a tag-guarded init() (the tag is whatever the
-// fork uses to gate its FIPS-enforcing code paths) before any caller's
-// main() or test body runs.
+// enforcement and is restricted to validated cryptography. Default
+// false. A downstream fork running FIPS-enforced builds sets this var
+// to true from a tag-guarded init(), where the tag is whatever the fork
+// uses to gate its FIPS-enforcing code paths. The init() runs before
+// any caller's main() or test body.
 //
 // Test code uses it to skip cases the FIPS-tagged binary cannot satisfy:
 //

buildvars/fips.go

@@ -25,11 +25,12 @@ import (
 	"github.com/dgraph-io/dgraph/v25/x"
 )
 
-// skipIfFIPS skips the current test when buildvars.FIPSEnabled is true. Upgrade-path
-// tests pin a specific upstream SHA for the "old" binary; that commit
-// predates any FIPS-enforcing toolchain, so attempting to build it
-// under a FIPS configuration either fails outright or produces a binary
-// that refuses to start. Semantically valid in non-FIPS builds.
+// skipIfFIPS skips the current test when buildvars.FIPSEnabled is true.
+// Upgrade-path tests pin a specific upstream SHA for the "old" binary;
+// that commit predates any FIPS-enforcing toolchain, so building it
+// under a FIPS configuration fails outright or produces a binary that
+// refuses to start. The test remains semantically valid in non-FIPS
+// builds.
 func skipIfFIPS(t *testing.T) {
 	if buildvars.FIPSEnabled {
 		t.Skip("upgrade-path test pins a pre-FIPS upstream SHA; skipping under FIPS build")

check_upgrade/check_upgrade_test.go

@@ -155,13 +155,13 @@ func initService(basename string, idx, grpcPort int) service {
 	svc.Image = opts.Image + ":" + opts.Tag
 	svc.ContainerName = containerName(svc.name)
 	svc.WorkingDir = fmt.Sprintf("/data/%s", svc.name)
-	// EmitUser is a public hook (compose/hooks.go); the upstream default
-	// returns "" so the generated compose service inherits the image's
-	// own USER directive. Downstream consumers that run dgraph as a
-	// non-root user under compose can override the hook to return a
-	// "uid:gid" string (e.g. "${UID:-65532}"), which is then emitted as
-	// the service's `user:` field. Bind-mounted host paths must be
-	// readable by that uid for the container to start cleanly.
+	// EmitUser is a public hook in compose/hooks.go. The upstream
+	// default returns "" so the generated compose service inherits the
+	// image's own USER directive. Downstream consumers that run dgraph
+	// as a non-root user under compose override the hook to return a
+	// "uid:gid" string such as "${UID:-65532}", which is emitted as the
+	// service's `user:` field. Bind-mounted host paths must be readable
+	// by that uid for the container to start cleanly.
 	if u := EmitUser(); u != "" {
 		svc.User = u
 	}

compose/compose.go

@@ -9,10 +9,11 @@ package main
 // See testutil/hooks.go for the full convention.
 
 // EmitUser returns the value for the generated `user:` field in docker
-// compose services. Default: empty string (no user override emitted —
-// matches upstream behavior where containers run as the image's default
-// user). Forks may return e.g. "${UID:-65532}" to pin services to the
-// host UID for bind-mount compatibility under nonroot runtime images.
+// compose services. Default: empty string, emitting no user override
+// and matching upstream behavior where containers run as the image's
+// default user. Forks may return, e.g., "${UID:-65532}" to pin services
+// to the host UID for bind-mount compatibility under nonroot runtime
+// images.
 var EmitUser = defaultEmitUser
 
 func defaultEmitUser() string { return "" }

compose/hooks.go

@@ -15,11 +15,11 @@ RUN rm -rf /var/lib/apt/lists/*
 # remove /var/lib/apt/lists/* to reduce image size.
 # see: https://docs.docker.com/develop/develop-images/dockerfile_best-practices
 #
-# Retry the install once on transient apt-get errors (most commonly the
-# `File has unexpected size... Mirror sync in progress?` race against
-# archive.ubuntu.com mid-publish, which surfaces frequently in CI). The
-# rm + sleep between attempts gives the mirror time to settle and forces
-# a fresh package-list fetch.
+# Retry the install once on transient apt-get errors. The most common
+# is the `File has unexpected size... Mirror sync in progress?` race
+# against archive.ubuntu.com mid-publish, which surfaces frequently in
+# CI. The rm + sleep between attempts gives the mirror time to settle
+# and forces a fresh package-list fetch.
 RUN set -eu; \
     install_pkgs() { \
         apt-get update && apt-get install -y --no-install-recommends \

contrib/Dockerfile

@@ -51,9 +51,9 @@ ifneq ($(strip $(BUILD_RACE)),)
 endif
 
 # jemalloc stuff
-# Check common package-manager install paths: /usr/local/lib (make install
-# from source), /usr/lib (apt-get libjemalloc-dev), /usr/lib/libjemalloc_pic.a
-# (apk add jemalloc-dev on Alpine/Wolfi).
+# Check common package-manager install paths: /usr/local/lib (make
+# install from source), /usr/lib (apt-get libjemalloc-dev), and
+# /usr/lib/libjemalloc_pic.a (apk add jemalloc-dev on Alpine/Wolfi).
 HAS_JEMALLOC = $(shell test -f /usr/local/lib/libjemalloc.a -o -f /usr/lib/libjemalloc.a -o -f /usr/lib/libjemalloc_pic.a && echo "jemalloc")
 JEMALLOC_URL = "https://github.com/jemalloc/jemalloc/releases/download/5.3.1/jemalloc-5.3.1.tar.bz2"
 
@@ -89,9 +89,10 @@ install: jemalloc
 		echo "Old SHA256:" `sha256sum $(INSTALL_TARGET) 2>/dev/null | cut -c-64` ; \
 	fi
 	@go mod tidy
-	@# Use 'go build -o' rather than 'go install': the latter honors the
-	@# package's default name (always "dgraph"), but we want to honor $(BIN)
-	@# so renames (e.g. fork binary) produce the correct file name.
+	@# Use 'go build -o' rather than 'go install': 'go install' honors
+	@# the package's default name (always "dgraph"), but we want to
+	@# honor $(BIN) so renames such as a fork binary produce the
+	@# correct file name.
 	@go build $(BUILD_FLAGS) -o $(INSTALL_TARGET)
 	@echo "Installed $(BIN) ($(GOOS)/$(GOARCH)) to $(INSTALL_TARGET)"
 	@if [ "$(HAS_SHA256SUM)" ] ; then \

dgraph/Makefile

@@ -8,61 +8,62 @@ package dgraphtest
 import "github.com/docker/docker/api/types/container"
 
 // This file declares public extensibility hooks for the dgraphtest test
-// harness. See testutil/hooks.go for the full convention. Each hook is
-// initialized to an unexported default that implements upstream behavior;
+// harness. See testutil/hooks.go for the full convention. Each hook
+// initializes to an unexported default that implements upstream behavior;
 // a private fork reassigns the public var from its own init().
 
 // ApplyContainerUser optionally sets cfg.User to pin a container to a
-// specific UID/GID. Default: no-op (container runs as the image's
-// default user). Forks that ship nonroot runtime images and want tests
+// specific UID/GID. Default: no-op, so the container runs as the image's
+// default user. Forks that ship nonroot runtime images and want tests
 // to run under the host UID (so bind-mounted paths are writable) set
 // cfg.User to "host-uid:host-gid".
 var ApplyContainerUser = defaultApplyContainerUser
 
 // WidenTempDirPerms optionally relaxes the 0700 default permissions of
-// os.MkdirTemp to allow a container's nonroot user to traverse the
+// os.MkdirTemp so a container's nonroot user can traverse the
 // bind-mounted path. Default: no-op. Forks with nonroot runtime images
 // set the mode to 0755.
 var WidenTempDirPerms = defaultWidenTempDirPerms
 
 // WidenSecretFilePerms optionally relaxes secret-file permissions from
-// the default 0600 to let a container's nonroot user read the file via a
-// bind-mount. Default: no-op. Forks with nonroot runtime images set 0644.
-// Tempdir isolation bounds the exposure to ephemeral test processes.
+// the default 0600 so a container's nonroot user can read the file via
+// a bind-mount. Default: no-op. Forks with nonroot runtime images set
+// 0644. Tempdir isolation bounds the exposure to ephemeral test
+// processes.
 var WidenSecretFilePerms = defaultWidenSecretFilePerms
 
 // GeneratePlugins optionally overrides the plugin-build flow used by
-// LocalCluster.GeneratePlugins. If handled=true, the caller uses the
+// LocalCluster.GeneratePlugins. When handled=true, the caller uses the
 // returned tokenizers string to populate the cluster's custom_tokenizers
-// arg and skips the default native-go-build path. If handled=false, the
-// caller falls through to the default in-process build. Default:
-// returns ("", false, nil) — delegate to upstream.
+// arg and skips the default native-go-build path. When handled=false,
+// the caller falls through to the default in-process build. Default:
+// returns ("", false, nil) and delegates to upstream.
 //
 // Params:
 //   - raceEnabled: forward the --race flag to the plugin build
-//   - tempBinDir: the cluster's per-test tempdir (host-side); a plugins/
-//     subdirectory will be created there and bind-mounted into the
-//     container-side build environment
+//   - tempBinDir: the cluster's per-test tempdir (host-side). The hook
+//     creates a plugins/ subdirectory there and bind-mounts it into the
+//     container-side build environment.
 //   - repoRoot: host path to the dgraph repo root, mounted so the
 //     builder sees testutil/custom_plugins/... source files
 //
 // The returned tokenizers string is the comma-separated list of .so
-// paths as seen by the alpha container at runtime (typically under
-// /gobin/plugins/…).
+// paths the alpha container sees at runtime, typically under
+// /gobin/plugins/.
 var GeneratePlugins = defaultGeneratePlugins
 
 // SetupLinuxBinaries optionally overrides the dgraph-binary staging
-// performed by LocalCluster.setupBinary for the Linux branch. If
+// LocalCluster.setupBinary performs for the Linux branch. When
 // handled=true, the caller returns err without executing the upstream
-// single-binary Linux path. Default: (false, nil) — delegate to
+// single-binary Linux path. Default: (false, nil) and delegates to
 // upstream.
 var SetupLinuxBinaries = defaultSetupLinuxBinaries
 
 // HostBinaryName optionally overrides the filename of the host-native
 // dgraph binary that LocalCluster.HostDgraphBinaryPath joins with
-// tempBinDir. Default: empty string (use upstream default path selection
-// based on runtime.GOOS). Forks may return e.g. "dgraph_host" to name a
-// separate host-native binary alongside a container-only binary.
+// tempBinDir. Default: empty string, which selects the upstream default
+// path based on runtime.GOOS. Forks may return, e.g., "dgraph_host" to
+// name a separate host-native binary alongside a container-only binary.
 var HostBinaryName = defaultHostBinaryName
 
 func defaultApplyContainerUser(cfg *container.Config) {}