more docs

Author: rssh

shared/src/main/scala/com/github/rssh/appcontext/AppContext.scala

@@ -2,25 +2,61 @@ package com.github.rssh.appcontext
 
 import scala.quoted.*
 
+/**
+ * Annotation to mark class as a key for component cache.
+ * Useful for cases when we have multiple implementation of some generic component.
+ * i.e.
+ * <code>
+ *   @appContextCacheClass[UserRepository]
+ *   class UserRepositoryTestImpl(using AppContextProviders[...]) extends UserRepository {
+ *     ...
+ *   }
+ * </code>
+ * @tparam T
+ */
 class appContextCacheClass[T] extends scala.annotation.StaticAnnotation
 
 
-
+/**
+ * Application context is a way, to resolve components dependencies.
+ * Each component should provide an AppContextProvider, and
+ * AppContext[Component] will instantiate this components with dependencies.
+ */
 object AppContext  {
 
-  
+   /**
+    * Get component from application context.
+    * For this component should have an implicit AppContextProvider.
+    * @see AppContextProvider
+    * @tparam T - component to instantiate
+    * @return
+    */
    def apply[T](using AppContextProvider[T]): T =
      summon[AppContextProvider[T]].get
 
+   /**
+    * Type for component cache.
+    * By convention, if component depends from cache then it's AppContextProvider should check
+    * if this component is already in cache and instantiate new (and update cache) only if it's not found.
+    */
    opaque type Cache = AppContextCacheMap[String, Any]
 
+    /**
+      * Type for cache key.
+      * By convention, usually this is a type.show.
+      */
    opaque type CacheKey[T] = String
 
+    /**
+      * Create empty cache.
+      * @return empty cache
+      */
    def newCache: Cache = AppContextCacheMap.empty
 
+
    inline def cacheKey[T] = ${ cacheKeyImpl[T] }
 
-   def cacheKeyImpl[T:Type](using Quotes): Expr[CacheKey[T]] = {
+   private def cacheKeyImpl[T:Type](using Quotes): Expr[CacheKey[T]] = {
       import quotes.reflect.*
       val annotationClass = TypeRepr.of[appContextCacheClass[?]]
       //val keyNameExpr = TypeRepr.of[T].classSymbol.get.annotations.find(_.tpe <:< annotationClass) match
@@ -45,16 +81,44 @@ object AppContext  {
    def customCacheKey[T](key: String): CacheKey[T] = key
 
    extension  (c: Cache)
-     
+
+    /**
+      * Get component from cache.
+      * @tparam T - component type
+      * @return Some(component) or None if component is not found.
+      */
     inline def get[T]: Option[T] =
         c.get(cacheKey[T]).asInstanceOf[Option[T]]
-     
+
+     /**
+      * Get component from cache or create new one and update cache.
+      * @param value - function to create new component
+      * @tparam T - component type
+      * @return just created or cached component
+      */
     inline def getOrCreate[T](value: => T): T =
        c.getOrElseUpdate(cacheKey[T], value).asInstanceOf[T]
-  
+
+     /**
+      * Put component to cache, replacing old if needed
+       * @param value
+      * @tparam T
+      */
     inline def put[T](value: T): Unit =
         c.put(cacheKey[T], value)
+
+    /**
+      * Modify component in cache.
+      * @param f - function to remap
+      * @tparam T - component type
+      */ 
+    inline def modify[T](f: Option[T] => Option[T]): Unit =
+        c.updateWith(cacheKey[T])(v => f(v.asInstanceOf[Option[T]]))
 
+    /**
+      * Remove component from cache.
+      * @tparam T - component type
+      */ 
     inline def remove[T]: Unit =
         c.remove(cacheKey[T])  
 

shared/src/main/scala/com/github/rssh/appcontext/AppContextProvider.scala

@@ -4,21 +4,42 @@ package com.github.rssh.appcontext
 import scala.compiletime.*
 import scala.quoted.*
 
+
+/**
+ * AppContextProvider is a type class that provides a value of type T
+ *
+ * When we have AppContextProvider for a type T, then we can resolve T
+ * for dependency injection, using AppContext[T] syntax.
+ * <code>
+ *   AppContext[T]
+ * </code>
+ */
 trait AppContextProvider[T] {
   def get: T
-
 }
 
 
 object AppContextProvider {
 
+  /**
+   * Create AppContextProvider for a value of type T
+   *
+   * @param value the value of type T
+   * @return AppContextProvider for the value
+   */
   def of[T](value: T): AppContextProvider[T] = new AppContextProvider[T]:
     override def get: T = value
 
+  /**
+   * Create default AppContextProvider for a implicit value of type T.
+   */
   given ofGiven[T](using T): AppContextProvider[T] with {
     def get: T = summon[T]
   }
 
+  /**
+   * Create AppContextProvider for T from a set of AppContextProviders[Xs], where Xs is a tuple of types containing T.
+   */
   given fromProviders[Xs <: NonEmptyTuple, X, N <: Int](using AppContextProvidersSearch[Xs], TupleIndex.OfSubtype[Xs, X, N]): AppContextProvider[X] =
     summon[AppContextProvidersSearch[Xs]].getProvider[X, N]
 

shared/src/test/scala/com/github/rssh/appcontext/AppContextCacheTest.scala

@@ -0,0 +1,33 @@
+package com.github.rssh.appcontext
+
+class AppContextCacheTest extends munit.FunSuite {
+
+  trait MyTrait {
+    def name: String
+  }
+
+  class OtherClass
+
+  test("AppContextCache") {
+    val cache = AppContext.newCache
+    cache.put(1)
+    cache.put[String]("AAAA")
+    val myTrait = cache.getOrCreate(new MyTrait {def name="myTrait"})
+    cache.put("QQQ")
+
+
+    assertEquals(cache.get[Int], Some(1))
+    assertEquals(cache.get[String], Some("AAAA"))
+    assertEquals(cache.get[java.lang.String], Some("QQQ"))
+    assertEquals(cache.get[MyTrait].map(_.name), Some("myTrait") )
+    assertEquals(cache.get[OtherClass], None)
+
+    cache.modify[Int]{
+      case Some(x) => Some(x+1)
+      case None => Some(0)
+    }
+    assertEquals(cache.get[Int], Some(2))
+
+  }
+
+}