better comment

apis/common/parent/interface.go

@@ -20,14 +20,18 @@ import (
 )
 
 type Parent interface {
-	// The external reference format of the Parent.
+	// The external format of the Parent.
 	String() string
-	// Check whether the desired Parent from `.spec` matches the actual GCP parent in `.status`.
-	// This function is the parent immutable check where most resources cannot change their parent.
-	// Config Connector decides to not check the parent immutable in CRD or webhook level.
+	// Verify that the desired parent (from .spec) matches the actual parent in .status.externalRef.
+	// This ensures the parent remains unchanged.
+	// We currently don't enforce parent immutability using a webhook or CRD CEL due to legacy reasons.
 	MatchActual(Parent) error
 }
 
+// ParentBuilder builds a Parent object from a ParentRef.
+// - ParentRef is the Config Connector API reference for identifying a resource's logical parent.
+// - The Parent object provides helper functions for parent-related logic in direct reconciliation.
 type ParentBuilder interface {
+	// Parent API reference builds its corresponding Parent object.
 	Build(ctx context.Context, reader client.Reader, othernamespace string, parent Parent) error
 }

apis/common/parent/project.go

@@ -44,6 +44,9 @@ type ProjectRef struct {
 	Namespace string `json:"namespace,omitempty"`
 }
 
+// Builds a the ProjectParent from ProjectRef.
+// If `projectRef.external` is given, parse projectID from External, otherwise find the ConfigConnector project
+// according to `projectRef.name` and `projectRef.namespace`.
 func (p *ProjectRef) Build(ctx context.Context, reader client.Reader, othernamespace string, parent Parent) error {
 	projectParent, ok := parent.(*ProjectParent)
 	if !ok {