Getting Started section in API docs (#172)

* Shows how to get started with the component either within or outside of the framework itself.

src/components/config/src/athena-config.cr

@@ -23,7 +23,23 @@ module Athena
 
   # Athena's Config component contains common types for configuring components/features, and managing `ACF::Parameters`.
   #
-  # See the [external documentation](https://athenaframework.org/components/config/) for more information.
+  # ## Getting Started
+  #
+  # If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+  # Otherwise, if using it outside of the framework, you will first need to add it as a dependency:
+  #
+  # ```yaml
+  # dependencies:
+  #   athena-config:
+  #     github: athena-framework/config
+  #     version: ~> 0.3.0
+  # ```
+  #
+  # Then run `shards install`, being sure to require it via `require "athena-config"`.
+  #
+  # From here, checkout the [manual](/components/config) for some additional information on how to use it both within and outside of the framework.
+  #
+  # INFO: DI parameter injection requires the [Athena::DependencyInjection][] component as well.
   module Config
     VERSION = "0.3.0"
 

src/components/console/src/athena-console.cr

@@ -70,6 +70,22 @@ alias ACON = Athena::Console
 #   ACON::Command::Status::SUCCESS
 # end
 # ```
+#
+# ## Getting Started
+#
+# If using this component outside of the [Athena Framework][Athena::Framework], you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-console:
+#     github: athena-framework/console
+#     version: ~> 0.1.0
+# ```
+#
+# Then run `shards install`.
+#
+# From here you can then setup your entry point file talked about earlier, being sure to require the component via `require "athena-console"`.
+# Finally, create/require your `ACON::Command`s, and customize the `ACON::Application` as needed.
 module Athena::Console
   VERSION = "0.1.1"
 

src/components/dependency_injection/src/athena-dependency_injection.cr

@@ -26,6 +26,30 @@ alias ADI = Athena::DependencyInjection
 #
 # Using interfaces allows changing the functionality of a type by just changing what service gets injected into it, such as via an alias.
 # See this [blog post](https://dev.to/blacksmoke16/dependency-injection-in-crystal-2d66#plug-and-play) for an example of this.
+#
+# ## Getting Started
+#
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/dependency_injection) for some additional information on how to use it within the framework.
+#
+# If using it outside of the framework, you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-dependency_injection:
+#     github: athena-framework/dependency-injection
+#     version: ~> 0.3.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-dependency_injection"`.
+#
+# From here integration of the component depends on the execution flow of your application, and how it uses [Fibers](https://crystal-lang.org/api/Fiber.html).
+# Since each fiber has its own container instance, if your application only uses Crystal's main fiber and is short lived, then you most likely only need to set up your services
+# and expose one of them as [public][Athena::DependencyInjection::Register--optional-arguments] to serve as the entry point.
+#
+# If your application is meant to be long lived, such as using a [HTTP::Server](https://crystal-lang.org/api/HTTP/Server.html), then you will want to ensure that each
+# fiber is truly independent from one another, with them not being reused or sharing state external to the container. An example of this is how `HTTP::Server` reuses fibers
+# for `connection: keep-alive` requests. Because of this, or in cases similar to, you may want to manually reset the container via `Fiber.current.container = ADI::ServiceContainer.new`.
 module Athena::DependencyInjection
   VERSION = "0.3.2"
 

src/components/event_dispatcher/src/athena-event_dispatcher.cr

@@ -80,6 +80,33 @@ alias AED = Athena::EventDispatcher
 # # * Checking if there is a listener(s) listening on a given `AED::Event`
 # dispatcher.has_listeners? ExceptionEvent # => true
 # ```
+#
+# ## Getting Started
+#
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/event_dispatcher) for some additional information on how to use it within the framework.
+#
+# If using it outside of the framework, you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-event_dispatcher:
+#     github: athena-framework/event-dispatcher
+#     version: ~> 0.1.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-event_dispatcher"`.
+#
+# From here you will want to define any `AED::EventListenerInterface` and/or custom `AED::Event`s as required by your application.
+# You will then need a way to create/register the listeners with an `AED::EventDispatcherInterface`.
+# If none of your listeners have any constructor arguments, you can most likely just call `.new` on the default implementation,
+# otherwise you will need to pass it an array of the instantiated listener types.
+#
+# The dispatcher should be created in a way that allows it to be used throughout the application such that any mutations that happen to the listeners are reflected on subsequent dispatches.
+#
+# WARNING: If using this component within the context of something that handles independent execution flows, such as a web framework, you will want there to be a dedicated dispatcher instance for each path.
+# This ensures that one flow will not leak state to any other flow, while still allowing flow specific mutations to be used.
+# Consider pairing this component with the [Athena::DependencyInjection][Athena::DependencyInjection--getting-started] component as a way to handle this.
 module Athena::EventDispatcher
   VERSION = "0.1.3"
 

src/components/image_size/src/athena-image_size.cr

@@ -12,6 +12,22 @@ alias AIS = Athena::ImageSize
 # The image is processed byte by byte, so large images can be handled without loading the full image into memory.
 #
 # WARNING: This component is _NOT_ intended to check if a file is a valid image and may return nonsensical values if given a non-image file.
+#
+# ## Getting Started
+#
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Otherwise, you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-image_size:
+#     github: athena-framework/image-size
+#     version: ~> 0.1.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-image_size"`.
+#
+# From here you can use `AIS::Image` as needed.
 module Athena::ImageSize
   VERSION = "0.1.0"
 

src/components/negotiation/src/athena-negotiation.cr

@@ -16,6 +16,22 @@ alias ANG = Athena::Negotiation
 # The `Athena::Negotiation` component allows an application to support [content negotiation](https://tools.ietf.org/html/rfc7231#section-5.3).
 # The component has no dependencies and is framework agnostic; supporting various negotiators.
 #
+# ## Getting Started
+#
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/negotiation) for some additional information on how to use it within the framework.
+#
+# If using it outside of the framework, you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-negotiation:
+#     github: athena-framework/negotiation
+#     version: ~> 0.1.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-negotiation"`.
+#
 # ## Usage
 #
 # The main type of `Athena::Negotiation` is `ANG::AbstractNegotiator` which is used to implement negotiators for each `Accept*` header.

src/components/routing/src/athena-routing.cr

@@ -64,6 +64,27 @@ alias ARTA = ART::Annotations
 # ```
 #
 # See the related types for more detailed information.
+#
+# ## Getting Started
+#
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/routing) for some additional information on how to use it within the framework.
+#
+# If using it outside of the framework, you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-routing:
+#     github: athena-framework/routing
+#     version: ~> 0.1.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-routing"`.
+#
+# From here you would want to create an `ART::RouteCollection`, register routes with it, [compile][Athena::Routing.compile(routes)] it.
+# Then an `ART::Matcher::URLMatcherInterface` or `ART::Matcher::RequestMatcherInterface` could then be used to determine which route matches a given path or `ART::Request`.
+#
+# TIP: Consider using the annotations provided by the component within `ART::Annotations` to handle route registration.
 module Athena::Routing
   VERSION = "0.1.1"
 

src/components/serializer/src/athena-serializer.cr

@@ -38,11 +38,10 @@ module YAML; end
 #
 # ## Getting Started
 #
-# The serializer component utilizes a module to specify that a type is serializable, as well as annotations to control how it gets (de)serialized.
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/serializer) for some additional information on how to use it within the framework.
 #
-# ### Installation
-#
-# Add the dependency to your `shard.yml`:
+# If using it outside of the framework, you will first need to add it as a dependency:
 #
 # ```yaml
 # dependencies:
@@ -51,9 +50,9 @@ module YAML; end
 #     version: ~> 0.2.0
 # ```
 #
-# Run `shards install`.
+# Then run `shards install`, being sure to require it via `require "athena-serializer"`.
 #
-# ### Usage
+# ## Usage
 #
 # See the `ASR::Annotations` namespace a complete list of annotations, as well as each annotation for more detailed information.
 #

src/components/spec/src/athena-spec.cr

@@ -5,6 +5,24 @@ require "./methods"
 require "./test_case"
 
 # A set of common [Spec](https://crystal-lang.org/api/Spec.html) compliant testing utilities/types.
+#
+# ## Getting Started
+#
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/spec) for some additional information on how to use it within the framework.
+#
+# If using it outside of the framework, you will first need to add it as a dependency:
+#
+# ```yaml
+# development_dependencies:
+#   athena-spec:
+#     github: athena-framework/spec
+#     version: ~> 0.2.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-spec"` within your `spec/spec_helper.cr` file.
+#
+# From here you can create some `ASPEC::TestCase`s, or make use of the provided `ASPEC::Methods`.
 module Athena::Spec
   VERSION = "0.2.6"
 

src/components/validator/src/athena-validator.cr

@@ -41,6 +41,22 @@ alias Assert = AVD::Annotations
 #
 # ## Getting Started
 #
+# If using this component within the [Athena Framework][Athena::Framework], it is already installed and required for you.
+# Checkout the [manual](/components/validator) for some additional information on how to use it within the framework.
+#
+# If using it outside of the framework, you will first need to add it as a dependency:
+#
+# ```yaml
+# dependencies:
+#   athena-validator:
+#     github: athena-framework/validator
+#     version: ~> 0.1.0
+# ```
+#
+# Then run `shards install`, being sure to require it via `require "athena-validator"`.
+#
+# ## Usage
+#
 # `Athena::Validator` comes with a set of common `AVD::Constraints` built in that any project could find useful.
 # When used on its own, the `Athena::Validator.validator` method can be used to obtain an `AVD::Validator::ValidatorInterface` instance
 # to validate a given value/object.