refactor(core): rename ResourceMarker methods to internal names

4 files changed, 51 insertions, 26 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 62ec971..9972466 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -178,6 +178,16 @@ None
 
     _No behavioral changes — the `build` feature provides identical functionality to the old `builds` feature. Downstream code using `builds` continues to work via the alias, but should migrate to `build`._
 
+8. **[`core`]** Renamed `ResourceMarker` methods from public names (`res_clone`, `res_default`, `modify`) to doc-hidden internal names (`__resource_marker_clone`, `__resource_marker_default`, `__resource_marker_modify`). These methods are internal implementation details of the resource injection system and should not be called directly by user code. By prefixing with `__` and adding `#[doc(hidden)]`, they are still technically accessible but hidden from documentation and tooling, reducing API surface confusion.
+
+    - **`res_clone()`** → **`__resource_marker_clone()`** — Internal method for cloning a resource value during resource injection.
+    - **`res_default()`** → **`__resource_marker_default()`** — Internal method for creating a default resource value during resource injection.
+    - **`modify<C>()`** → **`__resource_marker_modify<C>()`** — Internal method for in-place modification of a resource during resource injection.
+
+    All internal usages within `global_resource.rs` and `lazy_resource.rs` have been updated to use the renamed methods. Test code has been updated accordingly.
+
+    A new module `mingling_core::asset::core_invokes` has been added to provide a centralized location for internal invocation helpers.
+
 #### Features:
 
 1. **[`core`]** Added `RenderResult::new()` method for creating a new `RenderResult` with default values (empty text and exit code 0). This provides a more explicit and discoverable constructor compared to `RenderResult::default()`, making it clearer when a fresh result is being created for use with `write!`/`writeln!`.
diff --git a/mingling_core/src/asset/chain.rs b/mingling_core/src/asset/chain.rs
index 423e218..bd504d0 100644
--- a/mingling_core/src/asset/chain.rs
+++ b/mingling_core/src/asset/chain.rs
@@ -12,6 +12,7 @@ pub trait Chain<G> {
     #[cfg(feature = "async")]
     fn proc(p: Self::Previous) -> impl Future<Output = ChainProcess<G>> + Send;
 
+    /// Process the previous value and return a future that resolves to a [`ChainProcess<G>`](./enum.ChainProcess.html)
     #[cfg(not(feature = "async"))]
     fn proc(p: Self::Previous) -> ChainProcess<G>;
 }
diff --git a/mingling_core/src/asset/global_resource.rs b/mingling_core/src/asset/global_resource.rs
index 19374e7..18e4446 100644
--- a/mingling_core/src/asset/global_resource.rs
+++ b/mingling_core/src/asset/global_resource.rs
@@ -38,7 +38,7 @@ where
         {
             let mut new_res = match Arc::try_unwrap(std::mem::take(arc_res)) {
                 Ok(val) => val,
-                Err(arc) => (*arc).res_clone(),
+                Err(arc) => (*arc).__resource_marker_clone(),
             };
             let r = f(&mut new_res);
             *arc_res = Arc::new(new_res);
@@ -57,7 +57,7 @@ where
         Res: 'static + Default + ResourceMarker + Send + Sync,
     {
         let Ok(mut guard) = self.resources.lock() else {
-            let mut default_res = Res::res_default();
+            let mut default_res = Res::__resource_marker_default();
             return f(&mut default_res);
         };
         if let Some(arc_res) = guard
@@ -66,13 +66,13 @@ where
         {
             let mut new_res = match Arc::try_unwrap(std::mem::take(arc_res)) {
                 Ok(val) => val,
-                Err(arc) => (*arc).res_clone(),
+                Err(arc) => (*arc).__resource_marker_clone(),
             };
             let r = f(&mut new_res);
             *arc_res = Arc::new(new_res);
             r
         } else {
-            let mut default_res = Res::res_default();
+            let mut default_res = Res::__resource_marker_default();
             f(&mut default_res)
         }
     }
@@ -85,7 +85,7 @@ where
     #[must_use]
     pub fn __extract_res_mut<Res: 'static + Default + ResourceMarker + Send + Sync>(&self) -> Res {
         let Ok(mut guard) = self.resources.lock() else {
-            return Res::res_default();
+            return Res::__resource_marker_default();
         };
         if let Some(arc_res) = guard
             .get_mut(&TypeId::of::<Res>())
@@ -93,10 +93,10 @@ where
         {
             match Arc::try_unwrap(std::mem::take(arc_res)) {
                 Ok(val) => val,
-                Err(arc) => (*arc).res_clone(),
+                Err(arc) => (*arc).__resource_marker_clone(),
             }
         } else {
-            Res::res_default()
+            Res::__resource_marker_default()
         }
     }
 
@@ -136,7 +136,7 @@ where
         &self,
     ) -> GlobalResource<Res> {
         self.res()
-            .unwrap_or_else(|| GlobalResource::from(Arc::new(Res::res_default())))
+            .unwrap_or_else(|| GlobalResource::from(Arc::new(Res::__resource_marker_default())))
     }
 }
 
@@ -176,10 +176,21 @@ impl<ResType: 'static + Send + Sync> AsRef<ResType> for GlobalResource<ResType>
 
 /// Resource marker trait, types that implement the Clone and Default traits can be considered as resources
 pub trait ResourceMarker {
+    /// Clone the resource. This is an internal method used by the resource injection system
+    /// and should not be called directly by user code.
     #[must_use]
-    fn res_clone(&self) -> Self;
-    fn res_default() -> Self;
-    fn modify<C>(f: impl FnOnce(&mut Self))
+    #[doc(hidden)]
+    fn __resource_marker_clone(&self) -> Self;
+
+    /// Create a default instance of the resource. This is an internal method used by the
+    /// resource injection system and should not be called directly by user code.
+    #[doc(hidden)]
+    fn __resource_marker_default() -> Self;
+
+    /// Modify the resource using a closure. This is an internal method used by the resource
+    /// injection system and should not be called directly by user code.
+    #[doc(hidden)]
+    fn __resource_marker_modify<C>(f: impl FnOnce(&mut Self))
     where
         C: ProgramCollect<Enum = C> + 'static;
 }
@@ -188,15 +199,15 @@ impl<T> ResourceMarker for T
 where
     T: Default + Clone + Send + Sync + 'static,
 {
-    fn res_clone(&self) -> Self {
+    fn __resource_marker_clone(&self) -> Self {
         Clone::clone(self)
     }
 
-    fn res_default() -> Self {
+    fn __resource_marker_default() -> Self {
         Default::default()
     }
 
-    fn modify<C>(f: impl FnOnce(&mut Self))
+    fn __resource_marker_modify<C>(f: impl FnOnce(&mut Self))
     where
         C: ProgramCollect<Enum = C> + 'static,
     {
@@ -230,38 +241,41 @@ mod tests {
     #[test]
     fn resource_marker_i32_res_clone() {
         let val = 42i32;
-        let cloned = val.res_clone();
+        let cloned = val.__resource_marker_clone();
         assert_eq!(cloned, 42);
     }
 
     #[test]
     fn resource_marker_i32_res_default() {
-        assert_eq!(<i32 as ResourceMarker>::res_default(), 0i32);
+        assert_eq!(<i32 as ResourceMarker>::__resource_marker_default(), 0i32);
     }
 
     #[test]
     fn resource_marker_string_res_clone() {
         let val = "hello".to_string();
-        let cloned = val.res_clone();
+        let cloned = val.__resource_marker_clone();
         assert_eq!(cloned, "hello");
     }
 
     #[test]
     fn resource_marker_string_res_default() {
-        assert_eq!(<String as ResourceMarker>::res_default(), "");
+        assert_eq!(<String as ResourceMarker>::__resource_marker_default(), "");
     }
 
     #[test]
     fn resource_marker_vec_res_clone() {
         let val = vec![1, 2, 3];
-        let cloned = val.res_clone();
+        let cloned = val.__resource_marker_clone();
         assert_eq!(cloned, vec![1, 2, 3]);
     }
 
     #[test]
     fn resource_marker_vec_res_default() {
         let empty: Vec<i32> = vec![];
-        assert_eq!(<Vec<i32> as ResourceMarker>::res_default(), empty);
+        assert_eq!(
+            <Vec<i32> as ResourceMarker>::__resource_marker_default(),
+            empty
+        );
     }
 
     // Note: Tests for Program::with_resource, res(), res_or_route(), res_or_default(),
diff --git a/mingling_core/src/asset/lazy_resource.rs b/mingling_core/src/asset/lazy_resource.rs
index 918aeb2..3cb7563 100644
--- a/mingling_core/src/asset/lazy_resource.rs
+++ b/mingling_core/src/asset/lazy_resource.rs
@@ -280,7 +280,7 @@ where
 {
     /// Clones the lazy resource. The cloned resource retains any initialized value,
     /// but the initializer is reset to `T::default()`.
-    fn res_clone(&self) -> Self {
+    fn __resource_marker_clone(&self) -> Self {
         match &self.inner {
             LazyInner::Init(t, _) => Self {
                 inner: LazyInner::Init(t.clone(), None),
@@ -290,7 +290,7 @@ where
     }
 
     /// Returns a default lazy resource (uninitialized, using `T::default()` as the initializer).
-    fn res_default() -> Self
+    fn __resource_marker_default() -> Self
     where
         T: Default,
     {
@@ -298,7 +298,7 @@ where
     }
 
     /// Modifies the current lazy resource via the `this` context provided by `C`.
-    fn modify<C>(f: impl FnOnce(&mut Self))
+    fn __resource_marker_modify<C>(f: impl FnOnce(&mut Self))
     where
         C: ProgramCollect<Enum = C> + 'static,
     {
@@ -583,7 +583,7 @@ mod tests {
     fn res_clone_of_initialized_clones_value() {
         let mut r = LazyRes::new(|| vec![1, 2, 3]);
         r.get_ref();
-        let cloned = r.res_clone();
+        let cloned = r.__resource_marker_clone();
         assert!(cloned.is_initialized());
         assert_eq!(cloned.into_inner(), Some(vec![1, 2, 3]));
     }
@@ -591,14 +591,14 @@ mod tests {
     #[test]
     fn res_clone_of_uninitialized_creates_default() {
         let r: LazyRes<Vec<i32>> = LazyRes::new(|| vec![1, 2, 3]);
-        let cloned = r.res_clone();
+        let cloned = r.__resource_marker_clone();
         // The source is uninitialized, so res_clone returns a default lazy
         assert!(!cloned.is_initialized());
     }
 
     #[test]
     fn res_default_returns_uninitialized() {
-        let r: LazyRes<i32> = LazyRes::<i32>::res_default();
+        let r: LazyRes<i32> = LazyRes::<i32>::__resource_marker_default();
         assert!(!r.is_initialized());
     }