docs: improves hexdocs

mimiquate · Aug 23, 2024 · dea41e7 · dea41e7
1 parent fa2fc81
commit dea41e7
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 46 deletions.
diff --git a/lib/tower.ex b/lib/tower.ex
@@ -37,14 +37,23 @@ defmodule Tower do
 
   ## Example
 
-  ```elixir
-  try do
-    # possibly crashing code
-  catch
-    kind, reason ->
-      Tower.handle_caught(kind, reason, __STACKTRACE__)
-  end
-  ```
+      try do
+        # possibly crashing code
+      catch
+        # Note this will also catch and handle normal (`:normal` and `:shutdown`) exits
+        kind, reason ->
+          Tower.handle_caught(kind, reason, __STACKTRACE__)
+      end
+
+  ## Options
+
+    * `:plug_conn` - a `Plug.Conn` relevant to the caught error, if available, that may be used
+    by reporters to report useful context information. Be aware that the `Plug.Conn` may contain
+    user and/or system sensitive information, and it's up to each reporter to be cautious about
+    what to report or not.
+    * `:metadata` - a `Map` with additional information you want to provide about the event. It's
+    up to each reporter if and how to handle it.
+
   """
   @spec handle_caught(Exception.kind(), Event.reason(), Exception.stacktrace()) :: :ok
   @spec handle_caught(Exception.kind(), Event.reason(), Exception.stacktrace(), Keyword.t()) ::
@@ -59,14 +68,12 @@ defmodule Tower do
 
   ## Example
 
-  ```elixir
-  try do
-    # possibly crashing code
-  rescue
-    exception ->
-      Tower.handle_exception(exception, __STACKTRACE__)
-  end
-  ```
+      try do
+        # possibly crashing code
+      rescue
+        exception ->
+          Tower.handle_exception(exception, __STACKTRACE__)
+      end
   """
   @spec handle_exception(Exception.t(), Exception.stacktrace()) :: :ok
   @spec handle_exception(Exception.t(), Exception.stacktrace(), Keyword.t()) :: :ok
@@ -81,14 +88,12 @@ defmodule Tower do
 
   ## Example
 
-  ```elixir
-  try do
-    # possibly throwing code
-  catch
-    thrown_value ->
-      Tower.handle_throw(thrown_value, __STACKTRACE__)
-  end
-  ```
+      try do
+        # possibly throwing code
+      catch
+        thrown_value ->
+          Tower.handle_throw(thrown_value, __STACKTRACE__)
+      end
   """
   @spec handle_throw(term(), Exception.stacktrace()) :: :ok
   @spec handle_throw(term(), Exception.stacktrace(), Keyword.t()) :: :ok
@@ -102,14 +107,13 @@ defmodule Tower do
 
   ## Example
 
-  ```elixir
-  try do
-    # possibly exiting code
-  catch
-    :exit, exit_reason ->
-      Tower.handle_exit(exit_reason, __STACKTRACE__)
-  end
-  ```
+      try do
+        # possibly exiting code
+      catch
+        # Note this will also catch and handle normal (`:normal` and `:shutdown`) exits
+        :exit, exit_reason ->
+          Tower.handle_exit(exit_reason, __STACKTRACE__)
+      end
   """
   @spec handle_exit(term(), Exception.stacktrace()) :: :ok
   @spec handle_exit(term(), Exception.stacktrace(), Keyword.t()) :: :ok
@@ -123,15 +127,11 @@ defmodule Tower do
 
   ## Examples
 
-  ```elixir
-  Tower.handle_message(:emergency, "System is falling apart")
-  ```
-  ```elixir
-  Tower.handle_message(:error, "Unknown error has ocurred", metadata: %{any_key: "here"})
-  ```
-  ```elixir
-  Tower.handle_message(:info, "Just something interesting", metadata: %{interesting: "additional data"})
-  ```
+      Tower.handle_message(:emergency, "System is falling apart")
+
+      Tower.handle_message(:error, "Unknown error has ocurred", metadata: %{any_key: "here"})
+
+      Tower.handle_message(:info, "Just something interesting", metadata: %{interesting: "additional data"})
   """
   @spec handle_message(:logger.level(), term()) :: :ok
   @spec handle_message(:logger.level(), term(), Keyword.t()) :: :ok
@@ -140,12 +140,25 @@ defmodule Tower do
     |> report_event()
   end
 
-  @doc false
+  @doc """
+  Compares event level severity.
+
+  Returns true if `level1` severity is equal or greater than `level2` severity.
+
+  ## Examples
+
+      iex> Tower.equal_or_greater_level?(:emergency, :error)
+      true
+      iex> Tower.equal_or_greater_level?(%Tower.Event{level: :info}, :info)
+      true
+      iex> Tower.equal_or_greater_level?(:warning, :critical)
+      false
+  """
+  @spec equal_or_greater_level?(Event.t() | Event.level(), Event.level()) :: boolean()
   def equal_or_greater_level?(%Event{level: level1}, level2) when is_atom(level2) do
     equal_or_greater_level?(level1, level2)
   end
 
-  @doc false
   def equal_or_greater_level?(level1, level2) when is_atom(level1) and is_atom(level2) do
     :logger.compare_levels(level1, level2) in [:gt, :eq]
   end

diff --git a/lib/tower/event.ex b/lib/tower/event.ex
@@ -14,11 +14,18 @@ defmodule Tower.Event do
   @type error_kind :: :error | :exit | :throw
   @type non_error_kind :: :message
   @type reason :: Exception.t() | term()
+  @type level :: :logger.level()
 
+  @typedoc """
+  A representation of a tower captured event.
+
+  Tower converts every captured error and message into a struct of this type
+  before passing along to reporters.
+  """
   @type t :: %__MODULE__{
           id: Uniq.UUID.t(),
           datetime: DateTime.t(),
-          level: :logger.level(),
+          level: level(),
           kind: error_kind() | non_error_kind(),
           reason: reason(),
           stacktrace: Exception.stacktrace() | nil,

diff --git a/mix.exs b/mix.exs
@@ -67,8 +67,11 @@ defmodule Tower.MixProject do
 
   defp docs do
     [
-      main: "readme",
-      extras: ["README.md"]
+      main: "Tower",
+      extras: [
+        "README.md": [title: "README"],
+        "CHANGELOG.md": [title: "Changelog"]
+      ]
     ]
   end
 end