review comments: 1

Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

Author: rawahars

internal/controller/device/plan9/doc.go

@@ -1,21 +1,62 @@
 //go:build windows && !wcow
 
-// Package plan9 provides a controller for managing Plan9 file-share devices
+// Package plan9 provides a manager for managing Plan9 file-share devices
 // attached to a Utility VM (UVM).
 //
-// It handles attaching and detaching Plan9 shares to the VM via HCS modify
+// It handles adding and removing Plan9 shares on the host side via HCS modify
 // calls. Guest-side mount operations (mapped-directory requests) are handled
-// separately by the mount controller.
+// separately by the mount manager.
 //
-// The [Controller] interface is the primary entry point, with [Manager] as its
-// concrete implementation. A single [Manager] manages all Plan9 shares for a UVM.
+// # Deduplication and Reference Counting
+//
+// [Manager] deduplicates shares: if two callers add a share with identical
+// [AddOptions], the second call reuses the existing share and increments an
+// internal reference count rather than issuing a second HCS call. The share is
+// only removed from the VM when the last caller invokes [Manager.RemoveFromVM].
 //
 // # Lifecycle
 //
-// [Manager] tracks active shares by name in an internal map.
+// Each share progresses through the states below.
+// The happy path runs down the left column; the error path is on the right.
+//
+//	Allocate entry for the share
+//	            │
+//	            ▼
+//	┌─────────────────────┐
+//	│    sharePending     │
+//	└──────────┬──────────┘
+//	           │
+//	   ┌───────┴────────────────────────────────┐
+//	   │ AddPlan9 succeeds                      │ AddPlan9 fails
+//	   ▼                                        ▼
+//	┌─────────────────────┐         ┌──────────────────────┐
+//	│     shareAdded      │         │    shareInvalid      │
+//	└──────────┬──────────┘         └──────────────────────┘
+//	           │ RemovePlan9 succeeds   (auto-removed from map)
+//	           ▼
+//	┌─────────────────────┐
+//	│    shareRemoved     │  ← terminal; entry removed from map
+//	└─────────────────────┘
+//
+// State descriptions:
+//
+//   - [sharePending]: entered when a new entry is allocated (by [Manager.ResolveShareName]
+//     or the first [Manager.AddToVM] call). No HCS call has been made yet.
+//   - [shareAdded]: entered once [vmPlan9Manager.AddPlan9] succeeds;
+//     the share is live on the VM.
+//   - [shareInvalid]: entered when [vmPlan9Manager.AddPlan9] fails;
+//     the map entry is removed immediately so the next call can retry.
+//   - [shareRemoved]: terminal state entered once [vmPlan9Manager.RemovePlan9] succeeds.
+//
+// Method summary:
 //
-//   - [Controller.AddToVM] adds a share and records its name in the map.
-//     If the HCS call fails, the share is not recorded.
-//   - [Controller.RemoveFromVM] removes a share and deletes its name from the map.
-//     If the share is not in the map, the call is a no-op.
+//   - [Manager.ResolveShareName] pre-allocates a share name for the given [AddOptions]
+//     without issuing any HCS call. If a matching share is already tracked,
+//     the existing name is returned. This is useful for resolving downstream
+//     resource paths (e.g., guest mount paths) before the share is live.
+//   - [Manager.AddToVM] attaches the share, driving the HCS AddPlan9 call on
+//     the first caller and incrementing the reference count on subsequent ones.
+//     If the HCS call fails, the entry is removed so the next call can retry.
+//   - [Manager.RemoveFromVM] decrements the reference count and tears down the
+//     share only when the count reaches zero.
 package plan9