Improve documentation

Author: adriangs1996

docs/guide/mortymer-dependency-injection.md

@@ -27,6 +27,9 @@ When you include `Mortymer::DependenciesDsl`, you get access to the `inject` dir
 1. Create an instance variable `@user_repository`
 2. Automatically initialize it with an instance of `UserRepository`
 
+The name of the injected variable is the snake_case version of the class we are injecting by default. So
+for example `Repositories::UserRepository` will result in an instance variable called `@user_repository`
+
 ### Custom Variable Names
 
 You can customize the instance variable name using the `as` option:
@@ -66,54 +69,61 @@ end
 
 ## Advanced Usage
 
-### Dependency Scopes
-
-Mortymer supports different scopes for dependencies:
-
-#### Singleton Scope (Default)
-
-By default, dependencies are singleton-scoped, meaning the same instance is shared across the application:
+Just with the basic information, Mortymer already provides a really powerful and
+expressive system to declare dependencies, but as it is, is just a Fancy Factory or Initializer
+for your classes. Where Dependency Injection really shines, is when you are able to control some
+other aspects of the dependency injection cycle. For example, Mortymer does not interfere with your
+usual object initialization.
 
 ```ruby
-class UserService
+class MyService
   include Mortymer::DependenciesDsl
+  inject Mailer
 
-  inject UserRepository # Singleton by default
-end
+  def initialize(user)
+    # At this point we can be sure that the @mailer instance
+    # is already defined
+    @mailer.send_email("Hello user", user.email)
+    @user = user
+  end
 ```
 
-#### Request Scope
+It might not be clear what is happening here. What is really doing Mortymer is
+wrapping the `#initialize` method with the dependency resolving algorithm and if
+any `kwarg` passed to the `#initialize` method matches the name of the injected
+dependency, then Mortymer will use that as the dependency instead.
 
-For dependencies that should be unique per request:
+This means that you can call your previous service as:
 
 ```ruby
-class UserService
-  include Mortymer::DependenciesDsl
-
-  inject UserRepository, scope: :request
-end
+MyService.new(User.first) # will use the Mailer class to instantiate the @mailer variable
+MyService.new(User.first, mailer: instance_double(Mailer))  # will override @mailer with an instance_double
 ```
 
-#### Transient Scope
+### Dependency Scopes
 
-For dependencies that should be newly instantiated every time:
+Mortymer supports different scopes for dependencies:
 
-```ruby
-class UserService
-  include Mortymer::DependenciesDsl
+- By default, dependencies are transient, meaning you will get a new fresh instance each time you ask for one
+- Dependencies might be singleton, meaning each injection will provide the same instance
+- Dependencies might be lazy, basically, a block that might compute a value for your dependency
 
-  inject UserRepository, scope: :transient
-end
-```
+To change a dependency's scope, you need to register it in the Mortymer DI Container
 
-### Factory Registration
+#### Singleton Scope
 
-You can register custom factory methods for your dependencies:
+```ruby
+Mortymer.container.register_constant(Mailer, SingletonMailer.new)
+```
+
+#### Lazy Scope
 
 ```ruby
-Mortymer.configure do |config|
-  config.register_factory(UserRepository) do
-    UserRepository.new(connection: DatabaseConnection.current)
+Mortymer.container.register_constant(MAILER_ADMIN_ADDRESS) do
+  if some_condition?
+    "admin+#{Time.current}@example.com"
+  else
+    "admin-ex@example.com"
   end
 end
 ```
@@ -129,6 +139,12 @@ module UserRepositoryInterface
   end
 end
 
+class UserService
+  include Mortymer::DependenciesDsl
+
+  inject UserRepositoryInterface, as: :repo
+end
+
 class PostgresUserRepository
   include UserRepositoryInterface
   # implementation
@@ -140,259 +156,9 @@ class MongoUserRepository
 end
 
 # Register implementation
-Mortymer.configure do |config|
-  config.register_implementation(UserRepositoryInterface, PostgresUserRepository)
-end
-
-class UserService
-  include Mortymer::DependenciesDsl
-
-  inject UserRepositoryInterface
-end
-```
-
-## Testing
-
-### Mocking Dependencies
-
-Mortymer makes it easy to mock dependencies in tests:
-
-```ruby
-RSpec.describe UserService do
-  let(:repository_mock) { instance_double(UserRepository) }
-  let(:mailer_mock) { instance_double(UserMailer) }
-
-  before do
-    Mortymer.stub_dependency(UserRepository, repository_mock)
-    Mortymer.stub_dependency(UserMailer, mailer_mock)
-  end
-
-  it "creates a user" do
-    service = UserService.new
-    expect(repository_mock).to receive(:create)
-    expect(mailer_mock).to receive(:send_welcome_email)
-
-    service.create_user(name: "John")
-  end
-end
-```
-
-### Test-Specific Implementations
-
-You can also register test-specific implementations:
-
-```ruby
-class TestUserRepository
-  include UserRepositoryInterface
-
-  def initialize
-    @users = {}
-  end
-
-  def find(id)
-    @users[id]
-  end
-end
-
-RSpec.describe UserService do
-  before do
-    Mortymer.register_implementation(UserRepositoryInterface, TestUserRepository)
-  end
-end
-```
-
-## Best Practices
-
-### 1. Keep Dependencies Explicit
-
-Always use explicit constant references rather than strings for dependencies:
-
-```ruby
-# Good
-inject UserRepository
-
-# Avoid
-inject "user_repository"
-```
-
-### 2. Use Meaningful Names
-
-Choose descriptive names for your dependencies:
-
-```ruby
-# Good
-inject UserRepository, as: :active_users_repository
-
-# Less Clear
-inject UserRepository, as: :repo
-```
-
-### 3. Group Related Dependencies
-
-Keep related dependencies together and organize them logically:
-
-```ruby
-class UserService
-  include Mortymer::DependenciesDsl
-
-  # Authentication dependencies
-  inject AuthenticationService
-  inject TokenGenerator
-
-  # User management dependencies
-  inject UserRepository
-  inject UserMailer
+Mortymer.container.register_constant(UserRepositoryInterface, PostgresUserRepository.new)
 
-  # Logging/Monitoring
-  inject Logger
-  inject MetricsCollector
-end
-```
-
-### 4. Interface Segregation
-
-Create focused interfaces for your dependencies:
-
-```ruby
-module UserReader
-  def find(id); end
-  def list; end
-end
-
-module UserWriter
-  def create(attributes); end
-  def update(id, attributes); end
-end
-
-class UserRepository
-  include UserReader
-  include UserWriter
-end
-
-class UserService
-  include Mortymer::DependenciesDsl
-
-  inject UserReader  # Only inject what you need
-end
-```
-
-## Common Patterns
-
-### Service Objects
-
-```ruby
-class CreateUser
-  include Mortymer::DependenciesDsl
-
-  inject UserRepository
-  inject UserMailer
-  inject UserValidator
-
-  def call(params)
-    @user_validator.validate!(params)
-    user = @user_repository.create(params)
-    @user_mailer.send_welcome_email(user)
-    user
-  end
-end
-```
-
-### Decorators
-
-```ruby
-class LoggedUserRepository
-  include Mortymer::DependenciesDsl
-
-  inject UserRepository
-  inject Logger
-
-  def find(id)
-    @logger.info("Finding user: #{id}")
-    result = @user_repository.find(id)
-    @logger.info("Found user: #{result&.id}")
-    result
-  end
-end
-```
-
-## Configuration
-
-### Global Configuration
-
-```ruby
-Mortymer.configure do |config|
-  # Register default implementations
-  config.register_implementation(UserRepositoryInterface, PostgresUserRepository)
-
-  # Register factories
-  config.register_factory(Logger) do
-    Logger.new($stdout).tap do |logger|
-      logger.level = Rails.env.production? ? :info : :debug
-    end
-  end
-
-  # Configure scopes
-  config.set_scope(UserSession, :request)
-end
-```
-
-### Environment-Specific Configuration
-
-```ruby
-# config/initializers/mortymer.rb
-Mortymer.configure do |config|
-  if Rails.env.test?
-    config.register_implementation(UserRepositoryInterface, TestUserRepository)
-  elsif Rails.env.development?
-    config.register_implementation(UserRepositoryInterface, DevUserRepository)
-  else
-    config.register_implementation(UserRepositoryInterface, ProductionUserRepository)
-  end
-end
+# Then you can instantiate
+UserService.new # will use the PostgresUserRepository implementation
+UserService.new(repo: MongoUserRepository.new) # override the dependency to use a different one
 ```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Circular Dependencies**
-
-```ruby
-# This will raise a CircularDependencyError
-class UserService
-  include Mortymer::DependenciesDsl
-  inject AccountService
-end
-
-class AccountService
-  include Mortymer::DependenciesDsl
-  inject UserService  # Circular dependency!
-end
-```
-
-Solution: Refactor to remove the circular dependency or use method injection.
-
-2. **Missing Dependencies**
-
-```ruby
-# This will raise a DependencyNotFoundError
-class UserService
-  include Mortymer::DependenciesDsl
-  inject NonExistentService
-end
-```
-
-Solution: Ensure all dependencies are properly registered or the constants exist.
-
-3. **Scope Conflicts**
-
-```ruby
-# This might cause issues
-class UserService
-  include Mortymer::DependenciesDsl
-  inject SessionManager, scope: :request  # Request-scoped
-  inject UserRepository  # Singleton-scoped
-end
-```
-
-Solution: Be careful mixing different scopes and ensure it makes sense for your use case.