docs: trim verbose comments

Pass over the new doc/inline comments and tighten the ones whose payload
is the function name plus a single non-obvious WHY. Net -34 lines, no
substance lost.

  - clone.go restorePatchStorageConfigs / buildStateReplacements: drop the
    re-explanation of how the function's body works
  - cloudhypervisor + firecracker preflight + lock comments: keep the
    failure mode (outage if we kill first; corruption if we don't lock
    every writable disk) and drop the procedural restating
  - validateSnapshotIntegrity / preflightRestore / hasMemoryRangeFile /
    snapshotResidentBasename / writeSnapshotMeta / snapshotMeta + Mount
    Spec: collapse multi-paragraph docs to one or two sentences

Author: CMGS

hypervisor/cloudhypervisor/clone.go

@@ -267,14 +267,9 @@ func hasCidataRole(sc *types.StorageConfig) bool {
 	return sc.Role == types.StorageRoleCidata
 }
 
-// restorePatchStorageConfigs returns the disks to feed into patchCHConfig so
-// the disk count matches the snapshot's config.json. When the snapshot did
-// NOT carry cidata (cloudimg post-first-boot), ensureCloneCidata appended a
-// fresh cidata entry — patchCHConfig must not see it (snapshot config.json
-// has no slot for it; cidata is hot-plugged later).
-//
-// When the snapshot carried cidata, or for direct-boot/Windows VMs that
-// never have cidata, we pass everything through unchanged.
+// restorePatchStorageConfigs strips the cidata entry ensureCloneCidata
+// appended to a no-cidata snapshot, so patchCHConfig matches chCfg.Disks
+// count. Cidata is hot-plugged later.
 func restorePatchStorageConfigs(storageConfigs []*types.StorageConfig, directBoot, windows, hadCidataInSnapshot bool) []*types.StorageConfig {
 	if directBoot || windows || hadCidataInSnapshot {
 		return storageConfigs
@@ -329,14 +324,10 @@ func buildCmdline(storageConfigs []*types.StorageConfig, networkConfigs []*types
 	return cmdline.String()
 }
 
-// buildStateReplacements builds old→new string mappings for state.json patching.
-// Only disk paths need patching (snapshot paths → clone paths). When
-// ensureCloneCidata appended a fresh cidata entry, storageConfigs is one
-// longer than chCfg.Disks; the prefix-min iteration covers the entries the
-// snapshot already knew about, which is exactly what state.json references.
-//
-// MAC addresses are no longer patched here — hot-swap (vm.remove-device +
-// vm.add-net) replaces the entire virtio-net device with the correct MAC.
+// buildStateReplacements maps source disk paths to clone paths for
+// state.json patching. Iterates min(chCfg.Disks, storageConfigs) so an
+// appended cidata in storageConfigs doesn't desync the prefix.
+// MACs are not patched here; NIC hot-swap rewrites the virtio-net device.
 func buildStateReplacements(chCfg *chVMConfig, storageConfigs []*types.StorageConfig) map[string]string {
 	n := min(len(chCfg.Disks), len(storageConfigs))
 	m := make(map[string]string, n)

hypervisor/cloudhypervisor/direct.go

@@ -21,8 +21,7 @@ func (ch *CloudHypervisor) DirectClone(ctx context.Context, vmID string, vmCfg *
 // Files are handled per-type: hardlink for memory-range-*, reflink/copy for
 // the COW disk, plain copy for small metadata.
 func (ch *CloudHypervisor) DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error) {
-	// Validate CPU and snapshot integrity BEFORE killing the running VM —
-	// any failure post-kill costs an outage.
+	// Preflight before kill — a malformed snapshot must not cost an outage.
 	if err := hypervisor.ValidateHostCPU(vmCfg.CPU); err != nil {
 		return nil, err
 	}

hypervisor/cloudhypervisor/helper.go

@@ -48,11 +48,9 @@ func ReverseLayerSerials(storageConfigs []*types.StorageConfig) []string {
 	return serials
 }
 
-// validateSnapshotIntegrity is the CH-specific preflight wrapper around
-// hypervisor.ValidateSnapshotIntegrity: it runs the common checks, asserts
-// the sidecar mirrors snapshot config.json's disk shape, and verifies the
-// CH-specific runtime files (state.json + at least one memory-range-*) are
-// present so vm.restore won't fail post-kill.
+// validateSnapshotIntegrity is the CH preflight: common checks, sidecar/
+// config.json disk shape match, plus state.json + memory-range-* presence
+// so vm.restore won't fail post-kill.
 func validateSnapshotIntegrity(srcDir string, sidecar []*types.StorageConfig) error {
 	if err := hypervisor.ValidateSnapshotIntegrity(srcDir, sidecar); err != nil {
 		return err
@@ -89,9 +87,8 @@ func validateSnapshotIntegrity(srcDir string, sidecar []*types.StorageConfig) er
 	return nil
 }
 
-// hasMemoryRangeFile reports whether srcDir contains at least one CH
-// memory-range-* file. We can't enumerate the exact set without parsing
-// state.json, but a missing prefix is enough to fail vm.restore.
+// hasMemoryRangeFile reports whether srcDir has at least one CH
+// memory-range-* file. A missing prefix is enough to fail vm.restore.
 func hasMemoryRangeFile(srcDir string) (bool, error) {
 	entries, err := os.ReadDir(srcDir)
 	if err != nil {

hypervisor/cloudhypervisor/restore.go

@@ -31,9 +31,7 @@ func (ch *CloudHypervisor) Restore(ctx context.Context, vmRef string, vmCfg *typ
 	}
 	defer cleanupStaging()
 
-	// Pre-flight: validate the staged snapshot fully (sidecar shape, data
-	// disk files present, role sequence vs live record) BEFORE killing the
-	// running VM. A malformed snapshot must not cost an outage.
+	// Preflight before kill — a malformed snapshot must not cost an outage.
 	if err := ch.preflightRestore(stagingDir, rec); err != nil {
 		return nil, fmt.Errorf("snapshot preflight: %w", err)
 	}
@@ -94,10 +92,8 @@ func (ch *CloudHypervisor) restoreAfterExtract(ctx context.Context, vmID string,
 	}()
 
 	chConfigPath := filepath.Join(rec.RunDir, "config.json")
-	// Use the sidecar's length, which mirrors snapshot config.json's disk
-	// count. rec.StorageConfigs may carry trailing cidata that the snapshot
-	// (post-first-boot) doesn't — prefix-slicing trims it cleanly because
-	// cidata is always at the tail of rec.
+	// Use sidecar length; rec may have trailing cidata that the snapshot
+	// lacks (cloudimg post-first-boot), prefix-slice trims it.
 	meta, metaErr := loadSnapshotMeta(rec.RunDir)
 	if metaErr != nil {
 		return nil, fmt.Errorf("load snapshot meta: %w", metaErr)

hypervisor/cloudhypervisor/snapshot.go

@@ -15,13 +15,10 @@ import (
 	"github.com/cocoonstack/cocoon/utils"
 )
 
-// snapshotMetaFile is the cocoon-owned sidecar inside a CH snapshot.
-// It mirrors snapshot config.json's disk shape but carries Role/MountPoint/
-// FSType/DirectIO that the CH schema cannot.
+// snapshotMetaFile carries Role/MountPoint/FSType/DirectIO that CH's chDisk
+// schema can't hold; mirrors chCfg.Disks order and length.
 const snapshotMetaFile = "cocoon.json"
 
-// snapshotMeta is persisted as cocoon.json alongside CH state.json/config.json.
-// StorageConfigs is in the same order and length as snapshot config.json's disks.
 type snapshotMeta struct {
 	StorageConfigs []*types.StorageConfig `json:"storage_configs"`
 	BootConfig     *types.BootConfig      `json:"boot_config,omitempty"`
@@ -134,11 +131,10 @@ func (ch *CloudHypervisor) Snapshot(ctx context.Context, ref string) (*types.Sna
 	return ch.BuildSnapshotConfig(snapID, &rec), utils.TarDirStreamWithRemove(tmpDir), nil
 }
 
-// writeSnapshotMeta builds the cocoon.json sidecar. Sidecar mirrors the
-// snapshot's own config.json shape (chCfg.Disks order/length), not
-// activeDisks(rec) — the latter would diverge whenever a cloudimg VM is
-// snapshotted between FirstBooted=true and the next stop, since CH still
-// holds cidata in that window.
+// writeSnapshotMeta builds the cocoon.json sidecar by mirroring the
+// snapshot's config.json shape. Using activeDisks(rec) would diverge for a
+// cloudimg VM snapshotted post-FirstBooted but pre-restart: CH still holds
+// cidata, but activeDisks would skip it.
 func writeSnapshotMeta(tmpDir string, rec *hypervisor.VMRecord) error {
 	chCfg, _, err := parseCHConfig(filepath.Join(tmpDir, "config.json"))
 	if err != nil {

hypervisor/firecracker/direct.go

@@ -41,11 +41,9 @@ func (fc *Firecracker) DirectRestore(ctx context.Context, vmRef string, vmCfg *t
 		return nil, killErr
 	}
 
-	// Lock every writable disk (COW + data disks) so recoverStaleBackup heals
-	// stale clone backups before the restore overwrites the disks. Locking
-	// only the COW would let a leftover data-<x>.raw.cocoon-clone-backup
-	// survive, then a future clone would rename that backup back over the
-	// freshly restored data disk.
+	// Lock every writable disk so recoverStaleBackup heals stale
+	// data-*.raw.cocoon-clone-backup before restore overwrites them;
+	// otherwise a future clone would rename the backup over restored data.
 	var result *types.VM
 	if lockErr := withSourceWritableDisksLocked(rec.StorageConfigs, func() error {
 		if cleanErr := cleanSnapshotFiles(rec.RunDir); cleanErr != nil {

hypervisor/firecracker/helper.go

@@ -12,13 +12,9 @@ const pidFileName = "fc.pid"
 
 var runtimeFiles = []string{hypervisor.APISocketName, pidFileName, hypervisor.ConsoleSockName}
 
-// preflightRestore loads the FC sidecar, runs structural validation, asserts
-// the role sequence matches the live record's prefix, and confirms FC's
-// snapshot/load runtime files (vmstate + mem) are present. Called before
-// killing the running VM so a malformed snapshot is rejected without outage.
-//
-// FC has no config.json equivalent to compare against (vmstate is binary),
-// so the only cocoon-side disk-shape check is the sidecar itself.
+// preflightRestore is the FC preflight: common checks, role-sequence match,
+// vmstate + mem files. FC vmstate is binary so the sidecar is the only
+// cocoon-side disk-shape source — there's no chCfg counterpart.
 func (fc *Firecracker) preflightRestore(srcDir string, rec *hypervisor.VMRecord) error {
 	meta, err := loadSnapshotMeta(srcDir, fc.conf.RootDir, fc.conf.Config.RunDir)
 	if err != nil {

hypervisor/firecracker/restore.go

@@ -36,8 +36,7 @@ func (fc *Firecracker) Restore(ctx context.Context, vmRef string, vmCfg *types.V
 	}
 	defer cleanupStaging()
 
-	// Pre-flight: validate the staged snapshot fully BEFORE killing the
-	// running VM. A malformed snapshot must not cost an outage.
+	// Preflight before kill — a malformed snapshot must not cost an outage.
 	if err := fc.preflightRestore(stagingDir, rec); err != nil {
 		return nil, fmt.Errorf("snapshot preflight: %w", err)
 	}
@@ -47,11 +46,9 @@ func (fc *Firecracker) Restore(ctx context.Context, vmRef string, vmCfg *types.V
 		return nil, killErr
 	}
 
-	// Lock every writable disk (COW + data disks). withCOWPathLocked alone
-	// would leave a stale data-<x>.raw.cocoon-clone-backup unhealed; the next
-	// concurrent clone/snapshot would acquire that path's lock,
-	// recoverStaleBackup would rename the backup over the just-restored data
-	// disk, silently corrupting it.
+	// Lock every writable disk so recoverStaleBackup heals stale
+	// data-*.raw.cocoon-clone-backup before restore overwrites them;
+	// otherwise a future clone would rename the backup over restored data.
 	var result *types.VM
 	if lockErr := withSourceWritableDisksLocked(rec.StorageConfigs, func() error {
 		_ = os.Remove(cowPath)

hypervisor/firecracker/snapshot.go

@@ -60,10 +60,9 @@ func (fc *Firecracker) Snapshot(ctx context.Context, ref string) (*types.Snapsho
 		return nil, nil, fmt.Errorf("create temp dir: %w", err)
 	}
 
-	// Serialize the COW + data-disk copy with concurrent clone redirects.
-	// withSourceWritableDisksLocked locks every writable disk in dictionary
-	// order so a concurrent clone seeing the same source can't race the
-	// reflink against its rename+symlink redirect.
+	// Lock every writable disk so a concurrent clone's rename+symlink
+	// redirect can't race this snapshot's reflink. Dictionary order keeps
+	// concurrent callers deadlock-free.
 	if err := withSourceWritableDisksLocked(rec.StorageConfigs, func() error {
 		return fc.WithRunningVM(ctx, &rec, func(_ int) error {
 			if err := pauseVM(ctx, hc); err != nil {

hypervisor/utils.go

@@ -478,9 +478,8 @@ func createSparseFile(path string, size int64) error {
 }
 
 // snapshotResidentBasename returns the basename a sidecar entry's file should
-// have inside the snapshot dir, or "" if the disk is not stored alongside the
-// snapshot (i.e. shared base layers). The sidecar's Path field still points at
-// the source VM's runDir, so we strip back to the basename.
+// have inside srcDir, or "" for shared base layers (not in the snapshot tar).
+// Sidecar Path still references the source runDir, so we strip to basename.
 func snapshotResidentBasename(sc *types.StorageConfig) string {
 	switch sc.Role {
 	case types.StorageRoleData: