fix/update-docstrings

README.md

@@ -128,7 +128,7 @@ The key responsibilities are:
 
 *   applying all fields from the core resource to the cluster object during reconciliation (`Mutate(current client.Object)`)
 *   providing a stable identity for logging and error reporting (`Identity() string`)
-*   exposing a fresh copy of the baseline resource object (`DesiredDefaultObject()`)
+*   exposing a fresh copy of the baseline resource object (`Object()`)
 
 This abstraction separates **how an object should look** from **how the framework reconciles it**.
 

examples/component-architecture-basics/README.md

@@ -97,5 +97,5 @@ Instead of using complex `if/else` logic inside resource configuration, we use *
 ### Resource Interface
 The `Resource` interface in `pkg/component` is the central contract for all objects managed by the framework:
 - `Identity() string`: Returns a unique identifier for the resource (e.g., `apps/v1/Deployment/web-ui`).
-- `DesiredDefaultObject() (client.Object, error)`: Returns a fresh copy of the baseline resource object. This object represents the starting point for both creation and updates.
+- `Object() (client.Object, error)`: Returns a fresh copy of the baseline resource object before reconciliation. Returns the applied k8s object after reconciling.
 - `Mutate(current client.Object) error`: Applies the core baseline, feature mutation intents, and any deferred mutations (like suspension) to the provided `current` server object. It also synchronizes the internal state to reflect these changes.

pkg/component/resource.go

@@ -12,7 +12,7 @@ type Resource interface {
 	// Mutate applies all applicable mutations on the resource retrieved from the kubernetes api.
 	//
 	// If the object exists: `current` is the object fetched from the API server.
-	// If it does not exist: `current` is the same base object returned by DesiredDefaultObject() and passed into CreateOrUpdate,
+	// If it does not exist: `current` is the same base object returned by Object() and passed into CreateOrUpdate,
 	// not a fetched server object.
 	//
 	// The Resource implementation is responsible for applying all desired fields from its
@@ -21,17 +21,14 @@ type Resource interface {
 	//
 	// The mutations are applied every time the component is reconciled.
 	Mutate(current client.Object) error
-	// Object returns a copy of the managed resource object.
+	// Object returns a copy of the managed Kubernetes resource.
 	//
-	// Before reconciliation this object represents the baseline state of the resource before any feature-driven
-	// mutations or side effects are applied.
+	// The returned object's state depends on the reconciliation phase:
+	//   - Before reconciliation: Represents the baseline state before any mutations or side effects.
+	//   - After reconciliation: Represents the state as applied to the Kubernetes API, including all mutations.
 	//
-	// After reconciliation this object represents what is applied on the kubernetes api after mutations and side
-	// effects have been applied.
-	//
-	// Note that this method is mainly exposed for the Component reconciler and implementers should generally refrain
-	// from accessing this and gathering required data from applied kubernetes objects by implementing idioms provided
-	// by the module. E.g. data extractors provided by the DataExtractable interface.
+	// This method is primarily intended for use by the Component reconciler. Implementers should
+	// avoid calling this directly to retrieve data; instead, use provided patterns like DataExtractable.
 	Object() (client.Object, error)
 	// Identity returns a unique identifier for the resource in the format <apiVersion>/<kind>/<name>.
 	Identity() string