docs: Enhance module documentation and README

Comprehensively update documentation across all modules to improve developer experience:

- Add Development section to README.md with:
  - Code quality tools (Credo and Dialyzer) usage
  - Testing, formatting, and documentation generation commands
  - Clear requirements section for Elixir 1.18+ and Erlang OTP

- Expand @moduledoc for all 10 core modules with:
  - Comprehensive feature overviews
  - Architecture and design pattern explanations
  - Rich usage examples for common scenarios
  - Implementation details and best practices

- Enhanced module-specific documentation:
  - HTTP: Add streaming behavior, telemetry events, quick start
  - HTTP.Promise: Document Promise pattern with chaining examples
  - HTTP.Request: Explain :httpc.request/4 argument mapping
  - HTTP.Response: Document streaming vs buffered responses
  - HTTP.Headers: Add case-insensitive operations and parsing
  - HTTP.FormData: Document encoding selection and streaming uploads
  - HTTP.AbortController: Add "How It Works" with thread-safety details
  - HTTP.FetchOptions: Categorize and document all available options
  - HTTP.Telemetry: List all events with measurements and metadata
  - HTTPFetch.Application: Document supervision tree structure

- Achieve 100% module documentation coverage
- Verify clean documentation build with mix docs (no warnings/errors)

Author: GSMLG-BOT

README.md

@@ -243,6 +243,73 @@ The library handles:
 - Invalid URLs
 - Cancelled requests
 
+## Development
+
+This project uses several code quality tools to maintain high standards:
+
+### Code Quality Tools
+
+**Credo** - Static code analysis to enforce Elixir style guidelines and identify code smells:
+
+```bash
+# Run standard checks
+mix credo
+
+# Run with strict mode (includes readability checks)
+mix credo --strict
+
+# Explain a specific issue
+mix credo explain <issue_category>
+```
+
+**Dialyzer** - Static type analysis to catch type errors and inconsistencies:
+
+```bash
+# Run type checking
+mix dialyzer
+
+# Generate/rebuild PLT (first time setup, takes 2-3 minutes)
+mix dialyzer --plt
+```
+
+**ExDoc** - Generate comprehensive documentation:
+
+```bash
+# Generate HTML documentation
+mix docs
+
+# View generated docs
+open doc/index.html
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+mix test
+
+# Run specific test file
+mix test test/http_test.exs
+
+# Run with coverage
+mix test --cover
+```
+
+### Code Formatting
+
+```bash
+# Format all code
+mix format
+
+# Check formatting without changes
+mix format --check-formatted
+```
+
+## Requirements
+
+- Elixir 1.18+ (for built-in `JSON` module support)
+- Erlang OTP with `:inets`, `:ssl`, `:public_key` applications
+
 ## License
 
 MIT License

lib/http.ex

@@ -1,8 +1,75 @@
 defmodule HTTP do
   @moduledoc """
-  A module simulating the web browser's Fetch API in Elixir, using :httpc as the foundation.
-  Provides HTTP.Request, HTTP.Response, HTTP.Promise and a global-like fetch function with asynchronous
-  capabilities and an AbortController for request cancellation.
+  A browser-like HTTP fetch API for Elixir, built on Erlang's `:httpc` module.
+
+  This module provides a modern, Promise-based HTTP client interface similar to the
+  browser's `fetch()` API. It supports asynchronous requests, streaming, request
+  cancellation, and comprehensive telemetry integration.
+
+  ## Features
+
+  - **Async by default**: All requests use Task.Supervisor with `async_nolink/4`
+  - **Automatic streaming**: Responses >5MB or with unknown Content-Length automatically stream
+  - **Request cancellation**: Via `HTTP.AbortController` for aborting in-flight requests
+  - **Promise chaining**: JavaScript-like promise interface with `then/3` support
+  - **Telemetry integration**: Comprehensive event emission for monitoring and observability
+  - **Zero external dependencies**: Uses only Erlang/OTP built-in modules (except telemetry)
+
+  ## Quick Start
+
+      # Simple GET request
+      {:ok, response} =
+        HTTP.fetch("https://jsonplaceholder.typicode.com/posts/1")
+        |> HTTP.Promise.await()
+
+      # Parse JSON response
+      {:ok, json} = HTTP.Response.json(response)
+
+      # POST with JSON body
+      {:ok, response} =
+        HTTP.fetch("https://api.example.com/posts", [
+          method: "POST",
+          headers: %{"Content-Type" => "application/json"},
+          body: JSON.encode!(%{title: "Hello", body: "World"})
+        ])
+        |> HTTP.Promise.await()
+
+  ## Architecture
+
+  The library is structured around these core modules:
+
+  - `HTTP` - Main entry point with the `fetch/2` function
+  - `HTTP.Promise` - Promise wrapper around Tasks for async operations
+  - `HTTP.Request` - Request configuration struct
+  - `HTTP.Response` - Response struct with JSON/text parsing helpers
+  - `HTTP.Headers` - Header manipulation utilities
+  - `HTTP.FormData` - Multipart/form-data encoding with file upload support
+  - `HTTP.AbortController` - Request cancellation mechanism
+  - `HTTP.FetchOptions` - Options processing and validation
+  - `HTTP.Telemetry` - Telemetry event emission for monitoring
+
+  ## Streaming Behavior
+
+  Responses are automatically streamed when:
+
+  - Content-Length > 5MB
+  - Content-Length header is missing/unknown
+
+  Streaming responses have `body: nil` and `stream: pid` in the Response struct.
+  Use `HTTP.Response.read_all/1` or `HTTP.Response.write_to/2` to consume streams.
+
+  ## Telemetry Events
+
+  All events use the `[:http_fetch, ...]` prefix:
+
+  - `[:http_fetch, :request, :start]` - Request initiated
+  - `[:http_fetch, :request, :stop]` - Request completed
+  - `[:http_fetch, :request, :exception]` - Request failed
+  - `[:http_fetch, :streaming, :start]` - Streaming started
+  - `[:http_fetch, :streaming, :chunk]` - Stream chunk received
+  - `[:http_fetch, :streaming, :stop]` - Streaming completed
+
+  See `HTTP.Telemetry` for detailed event documentation.
   """
 
   alias HTTP.Request

lib/http/abort_controller.ex

@@ -1,12 +1,80 @@
 defmodule HTTP.AbortController do
   use Agent
 
-  @type state :: %{request_id: pid() | nil, signal_ref: reference(), aborted: boolean()}
-
   @moduledoc """
-  Provides request cancellation functionality similar to the browser's AbortController.
+  Request cancellation mechanism similar to the browser's AbortController API.
+
+  This module provides a way to abort in-flight HTTP requests using an Agent-based
+  controller. It's designed to work with the `HTTP.fetch/2` function via the
+  `:signal` option.
+
+  ## How It Works
+
+  1. Create an AbortController before making the request
+  2. Pass the controller to `HTTP.fetch/2` via the `:signal` option
+  3. Call `abort/1` on the controller to cancel the request
+  4. The awaiting Promise will receive an error result
+
+  ## Basic Usage
+
+      # Create a controller
+      controller = HTTP.AbortController.new()
+
+      # Start a long-running request with the controller
+      promise = HTTP.fetch("https://httpbin.org/delay/10",
+        signal: controller,
+        options: [timeout: 20_000]
+      )
+
+      # Abort the request (e.g., after 2 seconds)
+      :timer.sleep(2000)
+      HTTP.AbortController.abort(controller)
+
+      # The awaited promise will return an error
+      case HTTP.Promise.await(promise) do
+        {:error, reason} ->
+          IO.puts("Request was aborted: " <> inspect(reason))
+        response ->
+          IO.puts("Request completed before abort")
+      end
+
+  ## Advanced Usage
+
+      # Abort from another process
+      controller = HTTP.AbortController.new()
+
+      # Start request in background
+      Task.start(fn ->
+        promise = HTTP.fetch("https://slow-api.example.com", signal: controller)
+        result = HTTP.Promise.await(promise)
+        IO.inspect(result)
+      end)
+
+      # Abort from main process after some condition
+      :timer.sleep(1000)
+      if some_condition?() do
+        HTTP.AbortController.abort(controller)
+      end
+
+  ## Implementation Details
+
+  - Uses Elixir's `Agent` for state management
+  - Registers with a `Registry` for process tracking
+  - Calls `:httpc.cancel_request/1` internally to abort the request
+  - Thread-safe and can be called from any process
+  - Idempotent - calling `abort/1` multiple times is safe
+
+  ## State Management
+
+  The controller maintains the following state:
+
+  - `request_id` - PID of the active `:httpc` request (set automatically)
+  - `signal_ref` - Unique reference for registry lookup
+  - `aborted` - Boolean flag indicating abort status
   """
 
+  @type state :: %{request_id: pid() | nil, signal_ref: reference(), aborted: boolean()}
+
   @doc """
   Starts a new AbortController agent.
   Returns `{:ok, pid}` of the agent.

lib/http/fetch_options.ex

@@ -1,7 +1,85 @@
 defmodule HTTP.FetchOptions do
   @moduledoc """
-  Processes fetch options for HTTP requests, supporting flat map, keyword list,
-  and HTTP.FetchOptions struct formats. Handles conversion to :httpc.request arguments.
+  Options processing and validation for `HTTP.fetch/2` requests.
+
+  This module handles the conversion of various option formats (maps, keyword lists,
+  structs) into structured options for `:httpc.request/4`. It provides a flexible
+  API that supports both simple and advanced HTTP client configurations.
+
+  ## Options Categories
+
+  Options are divided into two main categories:
+
+  1. **HTTP Options** (3rd argument to `:httpc.request/4`) - Request-specific settings:
+     - `timeout` - Request timeout in milliseconds
+     - `connect_timeout` - Connection timeout in milliseconds
+     - `ssl` - SSL/TLS options
+     - `autoredirect` - Follow redirects automatically
+     - `proxy_auth` - Proxy authentication
+     - `version` - HTTP version
+     - `relaxed` - Relaxed parsing mode
+
+  2. **Client Options** (4th argument to `:httpc.request/4`) - Client behavior settings:
+     - `sync` - Synchronous/asynchronous mode (default: false)
+     - `stream` - Response streaming configuration
+     - `body_format` - Response body format (:string or :binary)
+     - `full_result` - Return full HTTP response
+     - `headers_as_is` - Preserve header case
+     - `socket_opts` - Socket-level options
+     - `receiver` - Custom receiver process
+     - `ipv6_host_with_brackets` - IPv6 host formatting
+
+  ## Basic Usage
+
+      # Simple options as keyword list
+      HTTP.fetch("https://api.example.com", [
+        method: "POST",
+        headers: %{"Content-Type" => "application/json"},
+        timeout: 10_000
+      ])
+
+      # Complex options with HTTP and client settings
+      HTTP.fetch("https://api.example.com", [
+        method: "GET",
+        timeout: 5_000,
+        connect_timeout: 2_000,
+        ssl: [verify: :verify_peer],
+        body_format: :binary
+      ])
+
+  ## Advanced Configuration
+
+      # Using options and opts keywords for fine control
+      HTTP.fetch("https://api.example.com", [
+        method: "POST",
+        body: "data",
+        # Request-specific options (3rd arg to :httpc.request)
+        options: [
+          timeout: 10_000,
+          connect_timeout: 5_000
+        ],
+        # Client-specific options (4th arg to :httpc.request)
+        opts: [
+          sync: false,
+          body_format: :binary
+        ]
+      ])
+
+  ## Flat vs Structured Options
+
+  The module supports both flat and structured option formats:
+
+      # Flat format (recommended for simplicity)
+      [method: "POST", timeout: 5_000, body_format: :binary]
+
+      # Structured format (for explicit control)
+      [
+        method: "POST",
+        options: [timeout: 5_000],
+        opts: [body_format: :binary]
+      ]
+
+  Both formats are equivalent; the module automatically categorizes options.
   """
 
   defstruct method: :get,

lib/http/form_data.ex

@@ -1,7 +1,62 @@
 defmodule HTTP.FormData do
   @moduledoc """
-  Handles HTTP form data and multipart/form-data encoding for file uploads.
-  Supports both regular form data and multipart uploads with streaming file support.
+  HTTP form data and multipart/form-data encoding for file uploads.
+
+  This module provides a convenient API for building form submissions with support
+  for both URL-encoded forms and multipart file uploads. It automatically chooses
+  the appropriate encoding based on the presence of file fields.
+
+  ## Encoding Selection
+
+  - **URL-encoded** (`application/x-www-form-urlencoded`): Used when form contains only text fields
+  - **Multipart** (`multipart/form-data`): Used when form contains file fields
+
+  ## Features
+
+  - **Streaming file uploads**: Efficiently upload large files using `File.Stream`
+  - **Automatic encoding**: Selects appropriate encoding based on content
+  - **Boundary generation**: Automatically generates unique multipart boundaries
+  - **Mixed content**: Support for both text fields and files in the same form
+
+  ## Basic Usage
+
+      # Simple form with text fields
+      form = HTTP.FormData.new()
+             |> HTTP.FormData.append_field("username", "john_doe")
+             |> HTTP.FormData.append_field("email", "[email protected]")
+
+      HTTP.fetch("https://api.example.com/signup", method: "POST", body: form)
+
+  ## File Upload
+
+      # Single file upload
+      file_stream = File.stream!("document.pdf")
+      form = HTTP.FormData.new()
+             |> HTTP.FormData.append_field("title", "My Document")
+             |> HTTP.FormData.append_file("document", "document.pdf", file_stream, "application/pdf")
+
+      HTTP.fetch("https://api.example.com/upload", method: "POST", body: form)
+
+  ## Multiple Files
+
+      # Upload multiple files
+      form = HTTP.FormData.new()
+             |> HTTP.FormData.append_field("description", "Photos from vacation")
+             |> HTTP.FormData.append_file("photo1", "beach.jpg", File.stream!("beach.jpg"), "image/jpeg")
+             |> HTTP.FormData.append_file("photo2", "sunset.jpg", File.stream!("sunset.jpg"), "image/jpeg")
+
+      HTTP.fetch("https://api.example.com/gallery", method: "POST", body: form)
+
+  ## Content Types
+
+  When uploading files, you can specify the MIME type. If not provided, it defaults
+  to `"application/octet-stream"`:
+
+      # With explicit content type
+      form |> HTTP.FormData.append_file("image", "photo.jpg", stream, "image/jpeg")
+
+      # With default content type
+      form |> HTTP.FormData.append_file("data", "data.bin", stream)
   """
 
   defstruct parts: [],