From ccbefb51fcec18d50bd528ae4eeaa1661e02332e Mon Sep 17 00:00:00 2001
From: Matt Sutton <git@mhs.fastmail.com>
Date: Mon, 29 Jun 2026 20:41:03 -0400
Subject: [PATCH] Document event struct modules to fix ExDoc warnings

The Track/Identify/Screen/Page/Group/Alias/Context structs are public API
(callers construct them directly, and Segmentry's public specs reference
their t() types), but each was @moduledoc false. ExDoc warned that
documentation referenced types in hidden modules.

Give each a concise moduledoc linking to the relevant Segment spec, and
group them under "Event structs" in the docs sidebar. The internal
Segmentry.Analytics.Types helper stays hidden. mix docs now builds with
zero warnings.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/segmentry/types.ex | 38 +++++++++++++++++++++++++++++++-------
 mix.exs                | 13 ++++++++++++-
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/lib/segmentry/types.ex b/lib/segmentry/types.ex
index 06b1cb5..4e368d2 100644
--- a/lib/segmentry/types.ex
+++ b/lib/segmentry/types.ex
@@ -13,7 +13,10 @@ defmodule Segmentry.Analytics.Types do
 end
 
 defmodule Segmentry.Analytics.Track do
-  @moduledoc false
+  @moduledoc """
+  A [`track`](https://segment.com/docs/connections/spec/track/) event — records
+  an action a user performed, named by `event`, with optional `properties`.
+  """
   @method "track"
 
   defstruct Segmentry.Analytics.Types.common_fields() ++
@@ -29,7 +32,10 @@ defmodule Segmentry.Analytics.Track do
 end
 
 defmodule Segmentry.Analytics.Identify do
-  @moduledoc false
+  @moduledoc """
+  An [`identify`](https://segment.com/docs/connections/spec/identify/) event —
+  ties a user to their `traits` (name, email, plan, etc.).
+  """
   @method "identify"
 
   defstruct Segmentry.Analytics.Types.common_fields() ++
@@ -44,7 +50,10 @@ defmodule Segmentry.Analytics.Identify do
 end
 
 defmodule Segmentry.Analytics.Alias do
-  @moduledoc false
+  @moduledoc """
+  An [`alias`](https://segment.com/docs/connections/spec/alias/) event — merges
+  two user identities by associating `userId` with a `previousId`.
+  """
   @method "alias"
 
   defstruct Segmentry.Analytics.Types.common_fields() ++
@@ -59,7 +68,10 @@ defmodule Segmentry.Analytics.Alias do
 end
 
 defmodule Segmentry.Analytics.Page do
-  @moduledoc false
+  @moduledoc """
+  A [`page`](https://segment.com/docs/connections/spec/page/) event — records a
+  web page view, named by `name`, with optional `properties`.
+  """
   @method "page"
 
   defstruct Segmentry.Analytics.Types.common_fields() ++
@@ -75,7 +87,10 @@ defmodule Segmentry.Analytics.Page do
 end
 
 defmodule Segmentry.Analytics.Screen do
-  @moduledoc false
+  @moduledoc """
+  A [`screen`](https://segment.com/docs/connections/spec/screen/) event — the
+  mobile equivalent of `Segmentry.Analytics.Page`, recording a screen view.
+  """
   @method "screen"
 
   defstruct Segmentry.Analytics.Types.common_fields() ++
@@ -91,7 +106,10 @@ defmodule Segmentry.Analytics.Screen do
 end
 
 defmodule Segmentry.Analytics.Group do
-  @moduledoc false
+  @moduledoc """
+  A [`group`](https://segment.com/docs/connections/spec/group/) event —
+  associates a user with a `groupId` (account/organization) and its `traits`.
+  """
   @method "group"
 
   defstruct Segmentry.Analytics.Types.common_fields() ++
@@ -107,7 +125,13 @@ defmodule Segmentry.Analytics.Group do
 end
 
 defmodule Segmentry.Analytics.Context do
-  @moduledoc false
+  @moduledoc """
+  Shared [context](https://segment.com/docs/connections/spec/common/#context)
+  attached to an event — library info, IP, locale, app, device, and so on.
+
+  Use `new/0` or `new/1` to build one; both populate `library` with Segmentry's
+  name and version automatically.
+  """
   @library_name Mix.Project.get().project()[:description]
   @library_version Mix.Project.get().project()[:version]
 
diff --git a/mix.exs b/mix.exs
index 50652ae..379c126 100644
--- a/mix.exs
+++ b/mix.exs
@@ -50,7 +50,18 @@ defmodule Segmentry.MixProject do
       main: "Segmentry",
       api_reference: false,
       source_ref: "v#{@version}",
-      source_url: @source_url
+      source_url: @source_url,
+      groups_for_modules: [
+        "Event structs": [
+          Segmentry.Analytics.Track,
+          Segmentry.Analytics.Identify,
+          Segmentry.Analytics.Screen,
+          Segmentry.Analytics.Page,
+          Segmentry.Analytics.Group,
+          Segmentry.Analytics.Alias,
+          Segmentry.Analytics.Context
+        ]
+      ]
     ]
   end
 end