cmd/viewer: add field comments to generated view methods

Extract field comments from AST and include them in generated view
methods. Comments are preserved from the original struct fields to
provide documentation for the view accessors.

Fixes #16958

Signed-off-by: Maisem Ali <[email protected]>

cmd/viewer/tests/tests_view.go

@@ -247,47 +247,41 @@ func (v *MapView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v MapView) Int() views.Map[string, int] { return views.MapOf(v.ж.Int) }
-
+func (v MapView) Int() views.Map[string, int]           { return views.MapOf(v.ж.Int) }
 func (v MapView) SliceInt() views.MapSlice[string, int] { return views.MapSliceOf(v.ж.SliceInt) }
-
 func (v MapView) StructPtrWithPtr() views.MapFn[string, *StructWithPtrs, StructWithPtrsView] {
 	return views.MapFnOf(v.ж.StructPtrWithPtr, func(t *StructWithPtrs) StructWithPtrsView {
 		return t.View()
 	})
 }
-
 func (v MapView) StructPtrWithoutPtr() views.MapFn[string, *StructWithoutPtrs, StructWithoutPtrsView] {
 	return views.MapFnOf(v.ж.StructPtrWithoutPtr, func(t *StructWithoutPtrs) StructWithoutPtrsView {
 		return t.View()
 	})
 }
-
 func (v MapView) StructWithoutPtr() views.Map[string, StructWithoutPtrs] {
 	return views.MapOf(v.ж.StructWithoutPtr)
 }
-
 func (v MapView) SlicesWithPtrs() views.MapFn[string, []*StructWithPtrs, views.SliceView[*StructWithPtrs, StructWithPtrsView]] {
 	return views.MapFnOf(v.ж.SlicesWithPtrs, func(t []*StructWithPtrs) views.SliceView[*StructWithPtrs, StructWithPtrsView] {
 		return views.SliceOfViews[*StructWithPtrs, StructWithPtrsView](t)
 	})
 }
-
 func (v MapView) SlicesWithoutPtrs() views.MapFn[string, []*StructWithoutPtrs, views.SliceView[*StructWithoutPtrs, StructWithoutPtrsView]] {
 	return views.MapFnOf(v.ж.SlicesWithoutPtrs, func(t []*StructWithoutPtrs) views.SliceView[*StructWithoutPtrs, StructWithoutPtrsView] {
 		return views.SliceOfViews[*StructWithoutPtrs, StructWithoutPtrsView](t)
 	})
 }
-
 func (v MapView) StructWithoutPtrKey() views.Map[StructWithoutPtrs, int] {
 	return views.MapOf(v.ж.StructWithoutPtrKey)
 }
-
 func (v MapView) StructWithPtr() views.MapFn[string, StructWithPtrs, StructWithPtrsView] {
 	return views.MapFnOf(v.ж.StructWithPtr, func(t StructWithPtrs) StructWithPtrsView {
 		return t.View()
 	})
 }
+
+// Unsupported views.
 func (v MapView) SliceIntPtr() map[string][]*int           { panic("unsupported") }
 func (v MapView) PointerKey() map[*string]int              { panic("unsupported") }
 func (v MapView) StructWithPtrKey() map[StructWithPtrs]int { panic("unsupported") }
@@ -389,8 +383,10 @@ func (v StructWithSlicesView) Prefixes() views.Slice[netip.Prefix] {
 	return views.SliceOf(v.ж.Prefixes)
 }
 func (v StructWithSlicesView) Data() views.ByteSlice[[]byte] { return views.ByteSliceOf(v.ж.Data) }
-func (v StructWithSlicesView) Structs() StructWithPtrs       { panic("unsupported") }
-func (v StructWithSlicesView) Ints() *int                    { panic("unsupported") }
+
+// Unsupported views.
+func (v StructWithSlicesView) Structs() StructWithPtrs { panic("unsupported") }
+func (v StructWithSlicesView) Ints() *int              { panic("unsupported") }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
 var _StructWithSlicesViewNeedsRegeneration = StructWithSlices(struct {
@@ -554,9 +550,10 @@ func (v GenericIntStructView[T]) Pointer() views.ValuePointer[T] {
 	return views.ValuePointerOf(v.ж.Pointer)
 }
 
-func (v GenericIntStructView[T]) Slice() views.Slice[T] { return views.SliceOf(v.ж.Slice) }
+func (v GenericIntStructView[T]) Slice() views.Slice[T]     { return views.SliceOf(v.ж.Slice) }
+func (v GenericIntStructView[T]) Map() views.Map[string, T] { return views.MapOf(v.ж.Map) }
 
-func (v GenericIntStructView[T]) Map() views.Map[string, T]  { return views.MapOf(v.ж.Map) }
+// Unsupported views.
 func (v GenericIntStructView[T]) PtrSlice() *T               { panic("unsupported") }
 func (v GenericIntStructView[T]) PtrKeyMap() map[*T]string   { panic("unsupported") }
 func (v GenericIntStructView[T]) PtrValueMap() map[string]*T { panic("unsupported") }
@@ -648,9 +645,10 @@ func (v GenericNoPtrsStructView[T]) Pointer() views.ValuePointer[T] {
 	return views.ValuePointerOf(v.ж.Pointer)
 }
 
-func (v GenericNoPtrsStructView[T]) Slice() views.Slice[T] { return views.SliceOf(v.ж.Slice) }
+func (v GenericNoPtrsStructView[T]) Slice() views.Slice[T]     { return views.SliceOf(v.ж.Slice) }
+func (v GenericNoPtrsStructView[T]) Map() views.Map[string, T] { return views.MapOf(v.ж.Map) }
 
-func (v GenericNoPtrsStructView[T]) Map() views.Map[string, T]  { return views.MapOf(v.ж.Map) }
+// Unsupported views.
 func (v GenericNoPtrsStructView[T]) PtrSlice() *T               { panic("unsupported") }
 func (v GenericNoPtrsStructView[T]) PtrKeyMap() map[*T]string   { panic("unsupported") }
 func (v GenericNoPtrsStructView[T]) PtrValueMap() map[string]*T { panic("unsupported") }
@@ -741,12 +739,13 @@ func (v GenericCloneableStructView[T, V]) Value() V { return v.ж.Value.View() }
 func (v GenericCloneableStructView[T, V]) Slice() views.SliceView[T, V] {
 	return views.SliceOfViews[T, V](v.ж.Slice)
 }
-
 func (v GenericCloneableStructView[T, V]) Map() views.MapFn[string, T, V] {
 	return views.MapFnOf(v.ж.Map, func(t T) V {
 		return t.View()
 	})
 }
+
+// Unsupported views.
 func (v GenericCloneableStructView[T, V]) Pointer() map[string]T      { panic("unsupported") }
 func (v GenericCloneableStructView[T, V]) PtrSlice() *T               { panic("unsupported") }
 func (v GenericCloneableStructView[T, V]) PtrKeyMap() map[*T]string   { panic("unsupported") }
@@ -942,25 +941,21 @@ func (v StructWithTypeAliasFieldsView) SliceWithPtrs() views.SliceView[*StructWi
 func (v StructWithTypeAliasFieldsView) SliceWithoutPtrs() views.SliceView[*StructWithoutPtrsAlias, StructWithoutPtrsAliasView] {
 	return views.SliceOfViews[*StructWithoutPtrsAlias, StructWithoutPtrsAliasView](v.ж.SliceWithoutPtrs)
 }
-
 func (v StructWithTypeAliasFieldsView) MapWithPtrs() views.MapFn[string, *StructWithPtrsAlias, StructWithPtrsAliasView] {
 	return views.MapFnOf(v.ж.MapWithPtrs, func(t *StructWithPtrsAlias) StructWithPtrsAliasView {
 		return t.View()
 	})
 }
-
 func (v StructWithTypeAliasFieldsView) MapWithoutPtrs() views.MapFn[string, *StructWithoutPtrsAlias, StructWithoutPtrsAliasView] {
 	return views.MapFnOf(v.ж.MapWithoutPtrs, func(t *StructWithoutPtrsAlias) StructWithoutPtrsAliasView {
 		return t.View()
 	})
 }
-
 func (v StructWithTypeAliasFieldsView) MapOfSlicesWithPtrs() views.MapFn[string, []*StructWithPtrsAlias, views.SliceView[*StructWithPtrsAlias, StructWithPtrsAliasView]] {
 	return views.MapFnOf(v.ж.MapOfSlicesWithPtrs, func(t []*StructWithPtrsAlias) views.SliceView[*StructWithPtrsAlias, StructWithPtrsAliasView] {
 		return views.SliceOfViews[*StructWithPtrsAlias, StructWithPtrsAliasView](t)
 	})
 }
-
 func (v StructWithTypeAliasFieldsView) MapOfSlicesWithoutPtrs() views.MapFn[string, []*StructWithoutPtrsAlias, views.SliceView[*StructWithoutPtrsAlias, StructWithoutPtrsAliasView]] {
 	return views.MapFnOf(v.ж.MapOfSlicesWithoutPtrs, func(t []*StructWithoutPtrsAlias) views.SliceView[*StructWithoutPtrsAlias, StructWithoutPtrsAliasView] {
 		return views.SliceOfViews[*StructWithoutPtrsAlias, StructWithoutPtrsAliasView](t)

cmd/viewer/viewer.go

@@ -9,6 +9,8 @@ import (
 	"bytes"
 	"flag"
 	"fmt"
+	"go/ast"
+	"go/token"
 	"go/types"
 	"html/template"
 	"log"
@@ -17,6 +19,7 @@ import (
 	"strings"
 
 	"tailscale.com/util/codegen"
+	"tailscale.com/util/mak"
 	"tailscale.com/util/must"
 )
 
@@ -104,16 +107,13 @@ func (v *{{.ViewName}}{{.TypeParamNames}}) UnmarshalJSONFrom(dec *jsontext.Decod
 {{define "valuePointerField"}}func (v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.ValuePointer[{{.FieldType}}] { return views.ValuePointerOf(v.ж.{{.FieldName}}) }
 
 {{end}}
-{{define "mapField"}}
-func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.Map[{{.MapKeyType}},{{.MapValueType}}] { return views.MapOf(v.ж.{{.FieldName}})}
+{{define "mapField"}}func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.Map[{{.MapKeyType}},{{.MapValueType}}] { return views.MapOf(v.ж.{{.FieldName}})}
 {{end}}
-{{define "mapFnField"}}
-func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.MapFn[{{.MapKeyType}},{{.MapValueType}},{{.MapValueView}}] { return views.MapFnOf(v.ж.{{.FieldName}}, func (t {{.MapValueType}}) {{.MapValueView}} {
+{{define "mapFnField"}}func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.MapFn[{{.MapKeyType}},{{.MapValueType}},{{.MapValueView}}] { return views.MapFnOf(v.ж.{{.FieldName}}, func (t {{.MapValueType}}) {{.MapValueView}} {
 	return {{.MapFn}}
 })}
 {{end}}
-{{define "mapSliceField"}}
-func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.MapSlice[{{.MapKeyType}},{{.MapValueType}}] { return views.MapSliceOf(v.ж.{{.FieldName}}) }
+{{define "mapSliceField"}}func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() views.MapSlice[{{.MapKeyType}},{{.MapValueType}}] { return views.MapSliceOf(v.ж.{{.FieldName}}) }
 {{end}}
 {{define "unsupportedField"}}func(v {{.ViewName}}{{.TypeParamNames}}) {{.FieldName}}() {{.FieldType}} {panic("unsupported")}
 {{end}}
@@ -142,7 +142,81 @@ func requiresCloning(t types.Type) (shallow, deep bool, base types.Type) {
 	return p, p, t
 }
 
-func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *types.Package) {
+type fieldNameKey struct {
+	typeName  string
+	fieldName string
+}
+
+// getFieldComments extracts field comments from the AST for a given struct type.
+func getFieldComments(syntax []*ast.File) map[fieldNameKey]string {
+	if len(syntax) == 0 {
+		return nil
+	}
+	var fieldComments map[fieldNameKey]string
+
+	// Search through all AST files in the package
+	for _, file := range syntax {
+		// Look for the type declaration
+		for _, decl := range file.Decls {
+			genDecl, ok := decl.(*ast.GenDecl)
+			if !ok || genDecl.Tok != token.TYPE {
+				continue
+			}
+
+			for _, spec := range genDecl.Specs {
+				typeSpec, ok := spec.(*ast.TypeSpec)
+				if !ok {
+					continue
+				}
+				typeName := typeSpec.Name.Name
+
+				// Check if it's a struct type
+				structType, ok := typeSpec.Type.(*ast.StructType)
+				if !ok {
+					continue
+				}
+
+				// Extract field comments
+				for _, field := range structType.Fields.List {
+					if len(field.Names) == 0 {
+						// Anonymous field or no names
+						continue
+					}
+
+					// Get the field name
+					fieldName := field.Names[0].Name
+					key := fieldNameKey{typeName, fieldName}
+
+					// Get the comment
+					var comment string
+					if field.Doc != nil && field.Doc.Text() != "" {
+						// Format the comment for Go code generation
+						comment = strings.TrimSpace(field.Doc.Text())
+						// Convert multi-line comments to proper Go comment format
+						var sb strings.Builder
+						for line := range strings.Lines(comment) {
+							sb.WriteString("// ")
+							sb.WriteString(line)
+						}
+						if sb.Len() > 0 {
+							comment = sb.String()
+						}
+					} else if field.Comment != nil && field.Comment.Text() != "" {
+						// Handle inline comments
+						comment = "// " + strings.TrimSpace(field.Comment.Text())
+					}
+					if comment != "" {
+						mak.Set(&fieldComments, key, comment)
+					}
+				}
+			}
+		}
+	}
+
+	return fieldComments
+}
+
+func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, fieldComments map[fieldNameKey]string) {
 	t, ok := typ.Underlying().(*types.Struct)
 	if !ok || codegen.IsViewType(t) {
 		return
@@ -182,6 +256,15 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 			log.Fatal(err)
 		}
 	}
+	writeTemplateWithComment := func(name, fieldName string) {
+		// Write the field comment if it exists
+		key := fieldNameKey{args.StructName, fieldName}
+		if comment, ok := fieldComments[key]; ok && comment != "" {
+			fmt.Fprintln(buf, comment)
+		}
+		writeTemplate(name)
+	}
+
 	writeTemplate("common")
 	for i := range t.NumFields() {
 		f := t.Field(i)
@@ -196,7 +279,7 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 		}
 		if !codegen.ContainsPointers(fieldType) || codegen.IsViewType(fieldType) || codegen.HasNoClone(t.Tag(i)) {
 			args.FieldType = it.QualifiedName(fieldType)
-			writeTemplate("valueField")
+			writeTemplateWithComment("valueField", fname)
 			continue
 		}
 		switch underlying := fieldType.Underlying().(type) {
@@ -207,7 +290,7 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 			case "byte":
 				args.FieldType = it.QualifiedName(fieldType)
 				it.Import("", "tailscale.com/types/views")
-				writeTemplate("byteSliceField")
+				writeTemplateWithComment("byteSliceField", fname)
 			default:
 				args.FieldType = it.QualifiedName(elem)
 				it.Import("", "tailscale.com/types/views")
@@ -217,35 +300,35 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 					case *types.Pointer:
 						if _, isIface := base.Underlying().(*types.Interface); !isIface {
 							args.FieldViewName = appendNameSuffix(it.QualifiedName(base), "View")
-							writeTemplate("viewSliceField")
+							writeTemplateWithComment("viewSliceField", fname)
 						} else {
-							writeTemplate("unsupportedField")
+							writeTemplateWithComment("unsupportedField", fname)
 						}
 						continue
 					case *types.Interface:
 						if viewType := viewTypeForValueType(elem); viewType != nil {
 							args.FieldViewName = it.QualifiedName(viewType)
-							writeTemplate("viewSliceField")
+							writeTemplateWithComment("viewSliceField", fname)
 							continue
 						}
 					}
-					writeTemplate("unsupportedField")
+					writeTemplateWithComment("unsupportedField", fname)
 					continue
 				} else if shallow {
 					switch base.Underlying().(type) {
 					case *types.Basic, *types.Interface:
-						writeTemplate("unsupportedField")
+						writeTemplateWithComment("unsupportedField", fname)
 					default:
 						if _, isIface := base.Underlying().(*types.Interface); !isIface {
 							args.FieldViewName = appendNameSuffix(it.QualifiedName(base), "View")
-							writeTemplate("viewSliceField")
+							writeTemplateWithComment("viewSliceField", fname)
 						} else {
-							writeTemplate("unsupportedField")
+							writeTemplateWithComment("unsupportedField", fname)
 						}
 					}
 					continue
 				}
-				writeTemplate("sliceField")
+				writeTemplateWithComment("sliceField", fname)
 			}
 			continue
 		case *types.Struct:
@@ -254,26 +337,26 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 			if codegen.ContainsPointers(strucT) {
 				if viewType := viewTypeForValueType(fieldType); viewType != nil {
 					args.FieldViewName = it.QualifiedName(viewType)
-					writeTemplate("viewField")
+					writeTemplateWithComment("viewField", fname)
 					continue
 				}
 				if viewType, makeViewFn := viewTypeForContainerType(fieldType); viewType != nil {
 					args.FieldViewName = it.QualifiedName(viewType)
 					args.MakeViewFnName = it.PackagePrefix(makeViewFn.Pkg()) + makeViewFn.Name()
-					writeTemplate("makeViewField")
+					writeTemplateWithComment("makeViewField", fname)
 					continue
 				}
-				writeTemplate("unsupportedField")
+				writeTemplateWithComment("unsupportedField", fname)
 				continue
 			}
-			writeTemplate("valueField")
+			writeTemplateWithComment("valueField", fname)
 			continue
 		case *types.Map:
 			m := underlying
 			args.FieldType = it.QualifiedName(fieldType)
 			shallow, deep, key := requiresCloning(m.Key())
 			if shallow || deep {
-				writeTemplate("unsupportedField")
+				writeTemplateWithComment("unsupportedField", fname)
 				continue
 			}
 			it.Import("", "tailscale.com/types/views")
@@ -358,7 +441,7 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 			default:
 				template = "unsupportedField"
 			}
-			writeTemplate(template)
+			writeTemplateWithComment(template, fname)
 			continue
 		case *types.Pointer:
 			ptr := underlying
@@ -368,9 +451,9 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 				if _, isIface := base.Underlying().(*types.Interface); !isIface {
 					args.FieldType = it.QualifiedName(base)
 					args.FieldViewName = appendNameSuffix(args.FieldType, "View")
-					writeTemplate("viewField")
+					writeTemplateWithComment("viewField", fname)
 				} else {
-					writeTemplate("unsupportedField")
+					writeTemplateWithComment("unsupportedField", fname)
 				}
 				continue
 			}
@@ -379,7 +462,7 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 			if viewType := viewTypeForValueType(base); viewType != nil {
 				args.FieldType = it.QualifiedName(base)
 				args.FieldViewName = it.QualifiedName(viewType)
-				writeTemplate("viewField")
+				writeTemplateWithComment("viewField", fname)
 				continue
 			}
 
@@ -389,7 +472,7 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 				baseTypeName := it.QualifiedName(base)
 				args.FieldType = baseTypeName
 				args.FieldViewName = appendNameSuffix(args.FieldType, "View")
-				writeTemplate("viewField")
+				writeTemplateWithComment("viewField", fname)
 				continue
 			}
 
@@ -397,18 +480,18 @@ func genView(buf *bytes.Buffer, it *codegen.ImportTracker, typ *types.Named, _ *
 			// and will not have a generated view type, use views.ValuePointer[T] as the field's view type.
 			// Its Get/GetOk methods return stack-allocated shallow copies of the field's value.
 			args.FieldType = it.QualifiedName(base)
-			writeTemplate("valuePointerField")
+			writeTemplateWithComment("valuePointerField", fname)
 			continue
 		case *types.Interface:
 			// If fieldType is an interface with a "View() {ViewType}" method, it can be used to clone the field.
 			// This includes scenarios where fieldType is a constrained type parameter.
 			if viewType := viewTypeForValueType(underlying); viewType != nil {
 				args.FieldViewName = it.QualifiedName(viewType)
-				writeTemplate("viewField")
+				writeTemplateWithComment("viewField", fname)
 				continue
 			}
 		}
-		writeTemplate("unsupportedField")
+		writeTemplateWithComment("unsupportedField", fname)
 	}
 	for i := range typ.NumMethods() {
 		f := typ.Method(i)
@@ -627,6 +710,7 @@ func main() {
 		log.Fatal(err)
 	}
 	it := codegen.NewImportTracker(pkg.Types)
+	fieldComments := getFieldComments(pkg.Syntax)
 
 	cloneOnlyType := map[string]bool{}
 	for _, t := range strings.Split(*flagCloneOnlyTypes, ",") {
@@ -654,7 +738,7 @@ func main() {
 		if !hasClone {
 			runCloner = true
 		}
-		genView(buf, it, typ, pkg.Types)
+		genView(buf, it, typ, fieldComments)
 	}
 	out := pkg.Name + "_view"
 	if *flagBuildTags == "test" {

cmd/viewer/viewer_test.go

@@ -53,6 +53,7 @@ func TestViewerImports(t *testing.T) {
 			if err != nil {
 				t.Fatal(err)
 			}
+			var fieldComments map[fieldNameKey]string // don't need it for this test.
 
 			var output bytes.Buffer
 			tracker := codegen.NewImportTracker(pkg)
@@ -65,7 +66,7 @@ func TestViewerImports(t *testing.T) {
 				if !ok {
 					t.Fatalf("%q is not a named type", tt.typeNames[i])
 				}
-				genView(&output, tracker, namedType, pkg)
+				genView(&output, tracker, namedType, fieldComments)
 			}
 
 			for _, pkg := range tt.wantImports {

drive/drive_view.go

@@ -83,9 +83,24 @@ func (v *ShareView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
+// Name is how this share appears on remote nodes.
 func (v ShareView) Name() string { return v.ж.Name }
+
+// Path is the path to the directory on this machine that's being shared.
 func (v ShareView) Path() string { return v.ж.Path }
-func (v ShareView) As() string   { return v.ж.As }
+
+// As is the UNIX or Windows username of the local account used for this
+// share. File read/write permissions are enforced based on this username.
+// Can be left blank to use the default value of "whoever is running the
+// Tailscale GUI".
+func (v ShareView) As() string { return v.ж.As }
+
+// BookmarkData contains security-scoped bookmark data for the Sandboxed
+// Mac application. The Sandboxed Mac application gains permission to
+// access the Share's folder as a result of a user selecting it in a file
+// picker. In order to retain access to it across restarts, it needs to
+// hold on to a security-scoped bookmark. That bookmark is stored here. See
+// https://developer.apple.com/documentation/security/app_sandbox/accessing_files_from_the_macos_app_sandbox#4144043
 func (v ShareView) BookmarkData() views.ByteSlice[[]byte] {
 	return views.ByteSliceOf(v.ж.BookmarkData)
 }

ipn/ipn_view.go

@@ -89,14 +89,47 @@ func (v *LoginProfileView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v LoginProfileView) ID() ProfileID                    { return v.ж.ID }
-func (v LoginProfileView) Name() string                     { return v.ж.Name }
-func (v LoginProfileView) NetworkProfile() NetworkProfile   { return v.ж.NetworkProfile }
-func (v LoginProfileView) Key() StateKey                    { return v.ж.Key }
+// ID is a unique identifier for this profile.
+// It is assigned on creation and never changes.
+// It may seem redundant to have both ID and UserProfile.ID
+// but they are different things. UserProfile.ID may change
+// over time (e.g. if a device is tagged).
+func (v LoginProfileView) ID() ProfileID { return v.ж.ID }
+
+// Name is the user-visible name of this profile.
+// It is filled in from the UserProfile.LoginName field.
+func (v LoginProfileView) Name() string { return v.ж.Name }
+
+// NetworkProfile is a subset of netmap.NetworkMap that we
+// store to remember information about the tailnet that this
+// profile was logged in with.
+//
+// This field was added on 2023-11-17.
+func (v LoginProfileView) NetworkProfile() NetworkProfile { return v.ж.NetworkProfile }
+
+// Key is the StateKey under which the profile is stored.
+// It is assigned once at profile creation time and never changes.
+func (v LoginProfileView) Key() StateKey { return v.ж.Key }
+
+// UserProfile is the server provided UserProfile for this profile.
+// This is updated whenever the server provides a new UserProfile.
 func (v LoginProfileView) UserProfile() tailcfg.UserProfile { return v.ж.UserProfile }
-func (v LoginProfileView) NodeID() tailcfg.StableNodeID     { return v.ж.NodeID }
-func (v LoginProfileView) LocalUserID() WindowsUserID       { return v.ж.LocalUserID }
-func (v LoginProfileView) ControlURL() string               { return v.ж.ControlURL }
+
+// NodeID is the NodeID of the node that this profile is logged into.
+// This should be stable across tagging and untagging nodes.
+// It may seem redundant to check against both the UserProfile.UserID
+// and the NodeID. However the NodeID can change if the node is deleted
+// from the admin panel.
+func (v LoginProfileView) NodeID() tailcfg.StableNodeID { return v.ж.NodeID }
+
+// LocalUserID is the user ID of the user who created this profile.
+// It is only relevant on Windows where we have a multi-user system.
+// It is assigned once at profile creation time and never changes.
+func (v LoginProfileView) LocalUserID() WindowsUserID { return v.ж.LocalUserID }
+
+// ControlURL is the URL of the control server that this profile is logged
+// into.
+func (v LoginProfileView) ControlURL() string { return v.ж.ControlURL }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
 var _LoginProfileViewNeedsRegeneration = LoginProfile(struct {
@@ -177,48 +210,253 @@ func (v *PrefsView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v PrefsView) ControlURL() string                          { return v.ж.ControlURL }
-func (v PrefsView) RouteAll() bool                              { return v.ж.RouteAll }
-func (v PrefsView) ExitNodeID() tailcfg.StableNodeID            { return v.ж.ExitNodeID }
-func (v PrefsView) ExitNodeIP() netip.Addr                      { return v.ж.ExitNodeIP }
-func (v PrefsView) AutoExitNode() ExitNodeExpression            { return v.ж.AutoExitNode }
+// ControlURL is the URL of the control server to use.
+//
+// If empty, the default for new installs, DefaultControlURL
+// is used. It's set non-empty once the daemon has been started
+// for the first time.
+//
+// TODO(apenwarr): Make it safe to update this with EditPrefs().
+// Right now, you have to pass it in the initial prefs in Start(),
+// which is the only code that actually uses the ControlURL value.
+// It would be more consistent to restart controlclient
+// automatically whenever this variable changes.
+//
+// Meanwhile, you have to provide this as part of
+// Options.LegacyMigrationPrefs or Options.UpdatePrefs when
+// calling Backend.Start().
+func (v PrefsView) ControlURL() string { return v.ж.ControlURL }
+
+// RouteAll specifies whether to accept subnets advertised by
+// other nodes on the Tailscale network. Note that this does not
+// include default routes (0.0.0.0/0 and ::/0), those are
+// controlled by ExitNodeID/IP below.
+func (v PrefsView) RouteAll() bool { return v.ж.RouteAll }
+
+// ExitNodeID and ExitNodeIP specify the node that should be used
+// as an exit node for internet traffic. At most one of these
+// should be non-zero.
+//
+// The preferred way to express the chosen node is ExitNodeID, but
+// in some cases it's not possible to use that ID (e.g. in the
+// linux CLI, before tailscaled has a netmap). For those
+// situations, we allow specifying the exit node by IP, and
+// ipnlocal.LocalBackend will translate the IP into an ID when the
+// node is found in the netmap.
+//
+// If the selected exit node doesn't exist (e.g. it's not part of
+// the current tailnet), or it doesn't offer exit node services, a
+// blackhole route will be installed on the local system to
+// prevent any traffic escaping to the local network.
+func (v PrefsView) ExitNodeID() tailcfg.StableNodeID { return v.ж.ExitNodeID }
+func (v PrefsView) ExitNodeIP() netip.Addr           { return v.ж.ExitNodeIP }
+
+// AutoExitNode is an optional expression that specifies whether and how
+// tailscaled should pick an exit node automatically.
+//
+// If specified, tailscaled will use an exit node based on the expression,
+// and will re-evaluate the selection periodically as network conditions,
+// available exit nodes, or policy settings change. A blackhole route will
+// be installed to prevent traffic from escaping to the local network until
+// an exit node is selected. It takes precedence over ExitNodeID and ExitNodeIP.
+//
+// If empty, tailscaled will not automatically select an exit node.
+//
+// If the specified expression is invalid or unsupported by the client,
+// it falls back to the behavior of [AnyExitNode].
+//
+// As of 2025-07-02, the only supported value is [AnyExitNode].
+// It's a string rather than a boolean to allow future extensibility
+// (e.g., AutoExitNode = "mullvad" or AutoExitNode = "geo:us").
+func (v PrefsView) AutoExitNode() ExitNodeExpression { return v.ж.AutoExitNode }
+
+// InternalExitNodePrior is the most recently used ExitNodeID in string form. It is set by
+// the backend on transition from exit node on to off and used by the
+// backend.
+//
+// As an Internal field, it can't be set by LocalAPI clients, rather it is set indirectly
+// when the ExitNodeID value is zero'd and via the set-use-exit-node-enabled endpoint.
 func (v PrefsView) InternalExitNodePrior() tailcfg.StableNodeID { return v.ж.InternalExitNodePrior }
-func (v PrefsView) ExitNodeAllowLANAccess() bool                { return v.ж.ExitNodeAllowLANAccess }
-func (v PrefsView) CorpDNS() bool                               { return v.ж.CorpDNS }
-func (v PrefsView) RunSSH() bool                                { return v.ж.RunSSH }
-func (v PrefsView) RunWebClient() bool                          { return v.ж.RunWebClient }
-func (v PrefsView) WantRunning() bool                           { return v.ж.WantRunning }
-func (v PrefsView) LoggedOut() bool                             { return v.ж.LoggedOut }
-func (v PrefsView) ShieldsUp() bool                             { return v.ж.ShieldsUp }
-func (v PrefsView) AdvertiseTags() views.Slice[string]          { return views.SliceOf(v.ж.AdvertiseTags) }
-func (v PrefsView) Hostname() string                            { return v.ж.Hostname }
-func (v PrefsView) NotepadURLs() bool                           { return v.ж.NotepadURLs }
-func (v PrefsView) ForceDaemon() bool                           { return v.ж.ForceDaemon }
-func (v PrefsView) Egg() bool                                   { return v.ж.Egg }
+
+// ExitNodeAllowLANAccess indicates whether locally accessible subnets should be
+// routed directly or via the exit node.
+func (v PrefsView) ExitNodeAllowLANAccess() bool { return v.ж.ExitNodeAllowLANAccess }
+
+// CorpDNS specifies whether to install the Tailscale network's
+// DNS configuration, if it exists.
+func (v PrefsView) CorpDNS() bool { return v.ж.CorpDNS }
+
+// RunSSH bool is whether this node should run an SSH
+// server, permitting access to peers according to the
+// policies as configured by the Tailnet's admin(s).
+func (v PrefsView) RunSSH() bool { return v.ж.RunSSH }
+
+// RunWebClient bool is whether this node should expose
+// its web client over Tailscale at port 5252,
+// permitting access to peers according to the
+// policies as configured by the Tailnet's admin(s).
+func (v PrefsView) RunWebClient() bool { return v.ж.RunWebClient }
+
+// WantRunning indicates whether networking should be active on
+// this node.
+func (v PrefsView) WantRunning() bool { return v.ж.WantRunning }
+
+// LoggedOut indicates whether the user intends to be logged out.
+// There are other reasons we may be logged out, including no valid
+// keys.
+// We need to remember this state so that, on next startup, we can
+// generate the "Login" vs "Connect" buttons correctly, without having
+// to contact the server to confirm our nodekey status first.
+func (v PrefsView) LoggedOut() bool { return v.ж.LoggedOut }
+
+// ShieldsUp indicates whether to block all incoming connections,
+// regardless of the control-provided packet filter. If false, we
+// use the packet filter as provided. If true, we block incoming
+// connections. This overrides tailcfg.Hostinfo's ShieldsUp.
+func (v PrefsView) ShieldsUp() bool { return v.ж.ShieldsUp }
+
+// AdvertiseTags specifies tags that should be applied to this node, for
+// purposes of ACL enforcement. These can be referenced from the ACL policy
+// document. Note that advertising a tag on the client doesn't guarantee
+// that the control server will allow the node to adopt that tag.
+func (v PrefsView) AdvertiseTags() views.Slice[string] { return views.SliceOf(v.ж.AdvertiseTags) }
+
+// Hostname is the hostname to use for identifying the node. If
+// not set, os.Hostname is used.
+func (v PrefsView) Hostname() string { return v.ж.Hostname }
+
+// NotepadURLs is a debugging setting that opens OAuth URLs in
+// notepad.exe on Windows, rather than loading them in a browser.
+//
+// apenwarr 2020-04-29: Unfortunately this is still needed sometimes.
+// Windows' default browser setting is sometimes screwy and this helps
+// users narrow it down a bit.
+func (v PrefsView) NotepadURLs() bool { return v.ж.NotepadURLs }
+
+// ForceDaemon specifies whether a platform that normally
+// operates in "client mode" (that is, requires an active user
+// logged in with the GUI app running) should keep running after the
+// GUI ends and/or the user logs out.
+//
+// The only current applicable platform is Windows. This
+// forced Windows to go into "server mode" where Tailscale is
+// running even with no users logged in. This might also be
+// used for macOS in the future. This setting has no effect
+// for Linux/etc, which always operate in daemon mode.
+func (v PrefsView) ForceDaemon() bool { return v.ж.ForceDaemon }
+
+// Egg is a optional debug flag.
+func (v PrefsView) Egg() bool { return v.ж.Egg }
+
+// AdvertiseRoutes specifies CIDR prefixes to advertise into the
+// Tailscale network as reachable through the current
+// node.
 func (v PrefsView) AdvertiseRoutes() views.Slice[netip.Prefix] {
 	return views.SliceOf(v.ж.AdvertiseRoutes)
 }
+
+// AdvertiseServices specifies the list of services that this
+// node can serve as a destination for. Note that an advertised
+// service must still go through the approval process from the
+// control server.
 func (v PrefsView) AdvertiseServices() views.Slice[string] {
 	return views.SliceOf(v.ж.AdvertiseServices)
 }
-func (v PrefsView) NoSNAT() bool                          { return v.ж.NoSNAT }
-func (v PrefsView) NoStatefulFiltering() opt.Bool         { return v.ж.NoStatefulFiltering }
+
+// NoSNAT specifies whether to source NAT traffic going to
+// destinations in AdvertiseRoutes. The default is to apply source
+// NAT, which makes the traffic appear to come from the router
+// machine rather than the peer's Tailscale IP.
+//
+// Disabling SNAT requires additional manual configuration in your
+// network to route Tailscale traffic back to the subnet relay
+// machine.
+//
+// Linux-only.
+func (v PrefsView) NoSNAT() bool { return v.ж.NoSNAT }
+
+// NoStatefulFiltering specifies whether to apply stateful filtering when
+// advertising routes in AdvertiseRoutes. The default is to not apply
+// stateful filtering.
+//
+// To allow inbound connections from advertised routes, both NoSNAT and
+// NoStatefulFiltering must be true.
+//
+// This is an opt.Bool because it was first added after NoSNAT, with a
+// backfill based on the value of that parameter. The backfill has been
+// removed since then, but the field remains an opt.Bool.
+//
+// Linux-only.
+func (v PrefsView) NoStatefulFiltering() opt.Bool { return v.ж.NoStatefulFiltering }
+
+// NetfilterMode specifies how much to manage netfilter rules for
+// Tailscale, if at all.
 func (v PrefsView) NetfilterMode() preftype.NetfilterMode { return v.ж.NetfilterMode }
-func (v PrefsView) OperatorUser() string                  { return v.ж.OperatorUser }
-func (v PrefsView) ProfileName() string                   { return v.ж.ProfileName }
-func (v PrefsView) AutoUpdate() AutoUpdatePrefs           { return v.ж.AutoUpdate }
-func (v PrefsView) AppConnector() AppConnectorPrefs       { return v.ж.AppConnector }
-func (v PrefsView) PostureChecking() bool                 { return v.ж.PostureChecking }
-func (v PrefsView) NetfilterKind() string                 { return v.ж.NetfilterKind }
+
+// OperatorUser is the local machine user name who is allowed to
+// operate tailscaled without being root or using sudo.
+func (v PrefsView) OperatorUser() string { return v.ж.OperatorUser }
+
+// ProfileName is the desired name of the profile. If empty, then the user's
+// LoginName is used. It is only used for display purposes in the client UI
+// and CLI.
+func (v PrefsView) ProfileName() string { return v.ж.ProfileName }
+
+// AutoUpdate sets the auto-update preferences for the node agent. See
+// AutoUpdatePrefs docs for more details.
+func (v PrefsView) AutoUpdate() AutoUpdatePrefs { return v.ж.AutoUpdate }
+
+// AppConnector sets the app connector preferences for the node agent. See
+// AppConnectorPrefs docs for more details.
+func (v PrefsView) AppConnector() AppConnectorPrefs { return v.ж.AppConnector }
+
+// PostureChecking enables the collection of information used for device
+// posture checks.
+//
+// Note: this should be named ReportPosture, but it was shipped as
+// PostureChecking in some early releases and this JSON field is written to
+// disk, so we just keep its old name. (akin to CorpDNS which is an internal
+// pref name that doesn't match the public interface)
+func (v PrefsView) PostureChecking() bool { return v.ж.PostureChecking }
+
+// NetfilterKind specifies what netfilter implementation to use.
+//
+// Linux-only.
+func (v PrefsView) NetfilterKind() string { return v.ж.NetfilterKind }
+
+// DriveShares are the configured DriveShares, stored in increasing order
+// by name.
 func (v PrefsView) DriveShares() views.SliceView[*drive.Share, drive.ShareView] {
 	return views.SliceOfViews[*drive.Share, drive.ShareView](v.ж.DriveShares)
 }
+
+// RelayServerPort is the UDP port number for the relay server to bind to,
+// on all interfaces. A non-nil zero value signifies a random unused port
+// should be used. A nil value signifies relay server functionality
+// should be disabled. This field is currently experimental, and therefore
+// no guarantees are made about its current naming and functionality when
+// non-nil/enabled.
 func (v PrefsView) RelayServerPort() views.ValuePointer[int] {
 	return views.ValuePointerOf(v.ж.RelayServerPort)
 }
 
+// AllowSingleHosts was a legacy field that was always true
+// for the past 4.5 years. It controlled whether Tailscale
+// peers got /32 or /127 routes for each other.
+// As of 2024-05-17 we're starting to ignore it, but to let
+// people still downgrade Tailscale versions and not break
+// all peer-to-peer networking we still write it to disk (as JSON)
+// so it can be loaded back by old versions.
+// TODO(bradfitz): delete this in 2025 sometime. See #12058.
 func (v PrefsView) AllowSingleHosts() marshalAsTrueInJSON { return v.ж.AllowSingleHosts }
-func (v PrefsView) Persist() persist.PersistView          { return v.ж.Persist.View() }
+
+// The Persist field is named 'Config' in the file for backward
+// compatibility with earlier versions.
+// TODO(apenwarr): We should move this out of here, it's not a pref.
+//
+//	We can maybe do that once we're sure which module should persist
+//	it (backend or frontend?)
+func (v PrefsView) Persist() persist.PersistView { return v.ж.Persist.View() }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
 var _PrefsViewNeedsRegeneration = Prefs(struct {
@@ -324,33 +562,52 @@ func (v *ServeConfigView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
+// TCP are the list of TCP port numbers that tailscaled should handle for
+// the Tailscale IP addresses. (not subnet routers, etc)
 func (v ServeConfigView) TCP() views.MapFn[uint16, *TCPPortHandler, TCPPortHandlerView] {
 	return views.MapFnOf(v.ж.TCP, func(t *TCPPortHandler) TCPPortHandlerView {
 		return t.View()
 	})
 }
 
+// Web maps from "$SNI_NAME:$PORT" to a set of HTTP handlers
+// keyed by mount point ("/", "/foo", etc)
 func (v ServeConfigView) Web() views.MapFn[HostPort, *WebServerConfig, WebServerConfigView] {
 	return views.MapFnOf(v.ж.Web, func(t *WebServerConfig) WebServerConfigView {
 		return t.View()
 	})
 }
 
+// Services maps from service name (in the form "svc:dns-label") to a ServiceConfig.
+// Which describes the L3, L4, and L7 forwarding information for the service.
 func (v ServeConfigView) Services() views.MapFn[tailcfg.ServiceName, *ServiceConfig, ServiceConfigView] {
 	return views.MapFnOf(v.ж.Services, func(t *ServiceConfig) ServiceConfigView {
 		return t.View()
 	})
 }
 
+// AllowFunnel is the set of SNI:port values for which funnel
+// traffic is allowed, from trusted ingress peers.
 func (v ServeConfigView) AllowFunnel() views.Map[HostPort, bool] {
 	return views.MapOf(v.ж.AllowFunnel)
 }
 
+// Foreground is a map of an IPN Bus session ID to an alternate foreground serve config that's valid for the
+// life of that WatchIPNBus session ID. This allows the config to specify ephemeral configs that are used
+// in the CLI's foreground mode to ensure ungraceful shutdowns of either the client or the LocalBackend does not
+// expose ports that users are not aware of. In practice this contains any serve config set via 'tailscale
+// serve' command run without the '--bg' flag. ServeConfig contained by Foreground is not expected itself to contain
+// another Foreground block.
 func (v ServeConfigView) Foreground() views.MapFn[string, *ServeConfig, ServeConfigView] {
 	return views.MapFnOf(v.ж.Foreground, func(t *ServeConfig) ServeConfigView {
 		return t.View()
 	})
 }
+
+// ETag is the checksum of the serve config that's populated
+// by the LocalClient through the HTTP ETag header during a
+// GetServeConfig request and is translated to an If-Match header
+// during a SetServeConfig request.
 func (v ServeConfigView) ETag() string { return v.ж.ETag }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
@@ -430,17 +687,23 @@ func (v *ServiceConfigView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
+// TCP are the list of TCP port numbers that tailscaled should handle for
+// the Tailscale IP addresses. (not subnet routers, etc)
 func (v ServiceConfigView) TCP() views.MapFn[uint16, *TCPPortHandler, TCPPortHandlerView] {
 	return views.MapFnOf(v.ж.TCP, func(t *TCPPortHandler) TCPPortHandlerView {
 		return t.View()
 	})
 }
 
+// Web maps from "$SNI_NAME:$PORT" to a set of HTTP handlers
+// keyed by mount point ("/", "/foo", etc)
 func (v ServiceConfigView) Web() views.MapFn[HostPort, *WebServerConfig, WebServerConfigView] {
 	return views.MapFnOf(v.ж.Web, func(t *WebServerConfig) WebServerConfigView {
 		return t.View()
 	})
 }
+
+// Tun determines if the service should be using L3 forwarding (Tun mode).
 func (v ServiceConfigView) Tun() bool { return v.ж.Tun }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
@@ -517,9 +780,29 @@ func (v *TCPPortHandlerView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v TCPPortHandlerView) HTTPS() bool          { return v.ж.HTTPS }
-func (v TCPPortHandlerView) HTTP() bool           { return v.ж.HTTP }
-func (v TCPPortHandlerView) TCPForward() string   { return v.ж.TCPForward }
+// HTTPS, if true, means that tailscaled should handle this connection as an
+// HTTPS request as configured by ServeConfig.Web.
+//
+// It is mutually exclusive with TCPForward.
+func (v TCPPortHandlerView) HTTPS() bool { return v.ж.HTTPS }
+
+// HTTP, if true, means that tailscaled should handle this connection as an
+// HTTP request as configured by ServeConfig.Web.
+//
+// It is mutually exclusive with TCPForward.
+func (v TCPPortHandlerView) HTTP() bool { return v.ж.HTTP }
+
+// TCPForward is the IP:port to forward TCP connections to.
+// Whether or not TLS is terminated by tailscaled depends on
+// TerminateTLS.
+//
+// It is mutually exclusive with HTTPS.
+func (v TCPPortHandlerView) TCPForward() string { return v.ж.TCPForward }
+
+// TerminateTLS, if non-empty, means that tailscaled should terminate the
+// TLS connections before forwarding them to TCPForward, permitting only the
+// SNI name with this value. It is only used if TCPForward is non-empty.
+// (the HTTPS mode uses ServeConfig.Web)
 func (v TCPPortHandlerView) TerminateTLS() string { return v.ж.TerminateTLS }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
@@ -597,9 +880,14 @@ func (v *HTTPHandlerView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v HTTPHandlerView) Path() string  { return v.ж.Path }
+// absolute path to directory or file to serve
+func (v HTTPHandlerView) Path() string { return v.ж.Path }
+
+// http://localhost:3000/, localhost:3030, 3030
 func (v HTTPHandlerView) Proxy() string { return v.ж.Proxy }
-func (v HTTPHandlerView) Text() string  { return v.ж.Text }
+
+// plaintext to serve (primarily for testing)
+func (v HTTPHandlerView) Text() string { return v.ж.Text }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
 var _HTTPHandlerViewNeedsRegeneration = HTTPHandler(struct {
@@ -675,6 +963,7 @@ func (v *WebServerConfigView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
+// mountPoint => handler
 func (v WebServerConfigView) Handlers() views.MapFn[string, *HTTPHandler, HTTPHandlerView] {
 	return views.MapFnOf(v.ж.Handlers, func(t *HTTPHandler) HTTPHandlerView {
 		return t.View()

types/dnstype/dnstype_view.go

@@ -84,10 +84,35 @@ func (v *ResolverView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
+// Addr is the address of the DNS resolver, one of:
+//   - A plain IP address for a "classic" UDP+TCP DNS resolver.
+//     This is the common format as sent by the control plane.
+//   - An IP:port, for tests.
+//   - "https://resolver.com/path" for DNS over HTTPS; currently
+//     as of 2022-09-08 only used for certain well-known resolvers
+//     (see the publicdns package) for which the IP addresses to dial DoH are
+//     known ahead of time, so bootstrap DNS resolution is not required.
+//   - "http://node-address:port/path" for DNS over HTTP over WireGuard. This
+//     is implemented in the PeerAPI for exit nodes and app connectors.
+//   - [TODO] "tls://resolver.com" for DNS over TCP+TLS
 func (v ResolverView) Addr() string { return v.ж.Addr }
+
+// BootstrapResolution is an optional suggested resolution for the
+// DoT/DoH resolver, if the resolver URL does not reference an IP
+// address directly.
+// BootstrapResolution may be empty, in which case clients should
+// look up the DoT/DoH server using their local "classic" DNS
+// resolver.
+//
+// As of 2022-09-08, BootstrapResolution is not yet used.
 func (v ResolverView) BootstrapResolution() views.Slice[netip.Addr] {
 	return views.SliceOf(v.ж.BootstrapResolution)
 }
+
+// UseWithExitNode designates that this resolver should continue to be used when an
+// exit node is in use. Normally, DNS resolution is delegated to the exit node but
+// there are situations where it is preferable to still use a Split DNS server and/or
+// global DNS server instead of the exit node.
 func (v ResolverView) UseWithExitNode() bool      { return v.ж.UseWithExitNode }
 func (v ResolverView) Equal(v2 ResolverView) bool { return v.ж.Equal(v2.ж) }
 

types/persist/persist_view.go

@@ -86,11 +86,18 @@ func (v *PersistView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v PersistView) PrivateNodeKey() key.NodePrivate    { return v.ж.PrivateNodeKey }
+func (v PersistView) PrivateNodeKey() key.NodePrivate { return v.ж.PrivateNodeKey }
+
+// needed to request key rotation
 func (v PersistView) OldPrivateNodeKey() key.NodePrivate { return v.ж.OldPrivateNodeKey }
 func (v PersistView) UserProfile() tailcfg.UserProfile   { return v.ж.UserProfile }
 func (v PersistView) NetworkLockKey() key.NLPrivate      { return v.ж.NetworkLockKey }
 func (v PersistView) NodeID() tailcfg.StableNodeID       { return v.ж.NodeID }
+
+// DisallowedTKAStateIDs stores the tka.State.StateID values which
+// this node will not operate network lock on. This is used to
+// prevent bootstrapping TKA onto a key authority which was forcibly
+// disabled.
 func (v PersistView) DisallowedTKAStateIDs() views.Slice[string] {
 	return views.SliceOf(v.ж.DisallowedTKAStateIDs)
 }

types/prefs/prefs_example/prefs_example_view.go

@@ -89,38 +89,68 @@ func (v *PrefsView) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
 	return nil
 }
 
-func (v PrefsView) ControlURL() prefs.Item[string]                    { return v.ж.ControlURL }
-func (v PrefsView) RouteAll() prefs.Item[bool]                        { return v.ж.RouteAll }
-func (v PrefsView) ExitNodeID() prefs.Item[tailcfg.StableNodeID]      { return v.ж.ExitNodeID }
-func (v PrefsView) ExitNodeIP() prefs.Item[netip.Addr]                { return v.ж.ExitNodeIP }
-func (v PrefsView) ExitNodePrior() tailcfg.StableNodeID               { return v.ж.ExitNodePrior }
-func (v PrefsView) ExitNodeAllowLANAccess() prefs.Item[bool]          { return v.ж.ExitNodeAllowLANAccess }
-func (v PrefsView) CorpDNS() prefs.Item[bool]                         { return v.ж.CorpDNS }
-func (v PrefsView) RunSSH() prefs.Item[bool]                          { return v.ж.RunSSH }
-func (v PrefsView) RunWebClient() prefs.Item[bool]                    { return v.ж.RunWebClient }
-func (v PrefsView) WantRunning() prefs.Item[bool]                     { return v.ж.WantRunning }
-func (v PrefsView) LoggedOut() prefs.Item[bool]                       { return v.ж.LoggedOut }
-func (v PrefsView) ShieldsUp() prefs.Item[bool]                       { return v.ж.ShieldsUp }
-func (v PrefsView) AdvertiseTags() prefs.ListView[string]             { return v.ж.AdvertiseTags.View() }
-func (v PrefsView) Hostname() prefs.Item[string]                      { return v.ж.Hostname }
-func (v PrefsView) NotepadURLs() prefs.Item[bool]                     { return v.ж.NotepadURLs }
-func (v PrefsView) ForceDaemon() prefs.Item[bool]                     { return v.ж.ForceDaemon }
-func (v PrefsView) Egg() prefs.Item[bool]                             { return v.ж.Egg }
+func (v PrefsView) ControlURL() prefs.Item[string]               { return v.ж.ControlURL }
+func (v PrefsView) RouteAll() prefs.Item[bool]                   { return v.ж.RouteAll }
+func (v PrefsView) ExitNodeID() prefs.Item[tailcfg.StableNodeID] { return v.ж.ExitNodeID }
+func (v PrefsView) ExitNodeIP() prefs.Item[netip.Addr]           { return v.ж.ExitNodeIP }
+
+// ExitNodePrior is an internal state rather than a preference.
+// It can be kept in the Prefs structure but should not be wrapped
+// and is ignored by the [prefs] package.
+func (v PrefsView) ExitNodePrior() tailcfg.StableNodeID      { return v.ж.ExitNodePrior }
+func (v PrefsView) ExitNodeAllowLANAccess() prefs.Item[bool] { return v.ж.ExitNodeAllowLANAccess }
+func (v PrefsView) CorpDNS() prefs.Item[bool]                { return v.ж.CorpDNS }
+func (v PrefsView) RunSSH() prefs.Item[bool]                 { return v.ж.RunSSH }
+func (v PrefsView) RunWebClient() prefs.Item[bool]           { return v.ж.RunWebClient }
+func (v PrefsView) WantRunning() prefs.Item[bool]            { return v.ж.WantRunning }
+func (v PrefsView) LoggedOut() prefs.Item[bool]              { return v.ж.LoggedOut }
+func (v PrefsView) ShieldsUp() prefs.Item[bool]              { return v.ж.ShieldsUp }
+
+// AdvertiseTags is a preference whose value is a slice of strings.
+// The value is atomic, and individual items in the slice should
+// not be modified after the preference is set.
+// Since the item type (string) is immutable, we can use [prefs.List].
+func (v PrefsView) AdvertiseTags() prefs.ListView[string] { return v.ж.AdvertiseTags.View() }
+func (v PrefsView) Hostname() prefs.Item[string]          { return v.ж.Hostname }
+func (v PrefsView) NotepadURLs() prefs.Item[bool]         { return v.ж.NotepadURLs }
+func (v PrefsView) ForceDaemon() prefs.Item[bool]         { return v.ж.ForceDaemon }
+func (v PrefsView) Egg() prefs.Item[bool]                 { return v.ж.Egg }
+
+// AdvertiseRoutes is a preference whose value is a slice of netip.Prefix.
+// The value is atomic, and individual items in the slice should
+// not be modified after the preference is set.
+// Since the item type (netip.Prefix) is immutable, we can use [prefs.List].
 func (v PrefsView) AdvertiseRoutes() prefs.ListView[netip.Prefix]     { return v.ж.AdvertiseRoutes.View() }
 func (v PrefsView) NoSNAT() prefs.Item[bool]                          { return v.ж.NoSNAT }
 func (v PrefsView) NoStatefulFiltering() prefs.Item[opt.Bool]         { return v.ж.NoStatefulFiltering }
 func (v PrefsView) NetfilterMode() prefs.Item[preftype.NetfilterMode] { return v.ж.NetfilterMode }
 func (v PrefsView) OperatorUser() prefs.Item[string]                  { return v.ж.OperatorUser }
 func (v PrefsView) ProfileName() prefs.Item[string]                   { return v.ж.ProfileName }
-func (v PrefsView) AutoUpdate() AutoUpdatePrefs                       { return v.ж.AutoUpdate }
-func (v PrefsView) AppConnector() AppConnectorPrefs                   { return v.ж.AppConnector }
-func (v PrefsView) PostureChecking() prefs.Item[bool]                 { return v.ж.PostureChecking }
-func (v PrefsView) NetfilterKind() prefs.Item[string]                 { return v.ж.NetfilterKind }
+
+// AutoUpdate contains auto-update preferences.
+// Each preference in the group can be configured and managed individually.
+func (v PrefsView) AutoUpdate() AutoUpdatePrefs { return v.ж.AutoUpdate }
+
+// AppConnector contains app connector-related preferences.
+// Each preference in the group can be configured and managed individually.
+func (v PrefsView) AppConnector() AppConnectorPrefs   { return v.ж.AppConnector }
+func (v PrefsView) PostureChecking() prefs.Item[bool] { return v.ж.PostureChecking }
+func (v PrefsView) NetfilterKind() prefs.Item[string] { return v.ж.NetfilterKind }
+
+// DriveShares is a preference whose value is a slice of *[drive.Share].
+// The value is atomic, and individual items in the slice should
+// not be modified after the preference is set.
+// Since the item type (*drive.Share) is mutable and implements [views.ViewCloner],
+// we need to use [prefs.StructList] instead of [prefs.List].
 func (v PrefsView) DriveShares() prefs.StructListView[*drive.Share, drive.ShareView] {
 	return prefs.StructListViewOf(&v.ж.DriveShares)
 }
 func (v PrefsView) AllowSingleHosts() prefs.Item[marshalAsTrueInJSON] { return v.ж.AllowSingleHosts }
-func (v PrefsView) Persist() persist.PersistView                      { return v.ж.Persist.View() }
+
+// Persist is an internal state rather than a preference.
+// It can be kept in the Prefs structure but should not be wrapped
+// and is ignored by the [prefs] package.
+func (v PrefsView) Persist() persist.PersistView { return v.ж.Persist.View() }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.
 var _PrefsViewNeedsRegeneration = Prefs(struct {

types/prefs/prefs_view_test.go

@@ -95,6 +95,9 @@ func (v TestPrefsView) AddrItem() Item[netip.Addr]               { return v.ж.A
 func (v TestPrefsView) StringStringMap() MapView[string, string] { return v.ж.StringStringMap.View() }
 func (v TestPrefsView) IntStringMap() MapView[int, string]       { return v.ж.IntStringMap.View() }
 func (v TestPrefsView) AddrIntMap() MapView[netip.Addr, int]     { return v.ж.AddrIntMap.View() }
+
+// Bundles are complex preferences that usually consist of
+// multiple parameters that must be configured atomically.
 func (v TestPrefsView) Bundle1() ItemView[*TestBundle, TestBundleView] {
 	return ItemViewOf(&v.ж.Bundle1)
 }
@@ -116,6 +119,10 @@ func (v TestPrefsView) IntBundleMap() StructMapView[int, *TestBundle, TestBundle
 func (v TestPrefsView) AddrBundleMap() StructMapView[netip.Addr, *TestBundle, TestBundleView] {
 	return StructMapViewOf(&v.ж.AddrBundleMap)
 }
+
+// Group is a nested struct that contains one or more preferences.
+// Each preference in a group can be configured individually.
+// Preference groups should be included directly rather than by pointers.
 func (v TestPrefsView) Group() TestPrefsGroup { return v.ж.Group }
 
 // A compilation failure here means this code must be regenerated, with the command at the top of this file.