From 88ade75ec50ade276533be7dc90bf2bc320ddbd6 Mon Sep 17 00:00:00 2001
From: Kayla Firestack <kfirestack@mbta.com>
Date: Thu, 19 Sep 2024 18:01:37 -0400
Subject: [PATCH 1/3] feat:doc: stub doc headers for database tables

`mix docs` doesn't generate anything for these modules if `@moduledoc false` is set, but we're using `TypedEctoSchema` now which _does_ generate type information, which can be surfaced by `ExDoc`.

It's also impossible to link to modules in documentation if `@moduledoc false` is set.
---
 lib/notifications/db/block_waiver.ex      | 4 +++-
 lib/notifications/db/bridge_movement.ex   | 4 +++-
 lib/notifications/db/notification.ex      | 4 +++-
 lib/notifications/db/notification_user.ex | 4 +++-
 lib/skate/detours/db/detour.ex            | 4 +++-
 lib/skate/settings/db/route_tab.ex        | 4 +++-
 lib/skate/settings/db/test_group.ex       | 4 +++-
 lib/skate/settings/db/test_group_user.ex  | 4 +++-
 lib/skate/settings/db/user.ex             | 4 +++-
 lib/skate/settings/db/user_settings.ex    | 4 +++-
 10 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/lib/notifications/db/block_waiver.ex b/lib/notifications/db/block_waiver.ex
index 47dbdc065..584044b7d 100644
--- a/lib/notifications/db/block_waiver.ex
+++ b/lib/notifications/db/block_waiver.ex
@@ -1,5 +1,7 @@
 defmodule Notifications.Db.BlockWaiver do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `block_waivers` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/notifications/db/bridge_movement.ex b/lib/notifications/db/bridge_movement.ex
index fa2583258..47fe757d4 100644
--- a/lib/notifications/db/bridge_movement.ex
+++ b/lib/notifications/db/bridge_movement.ex
@@ -1,5 +1,7 @@
 defmodule Notifications.Db.BridgeMovement do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `bridge_movements` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/notifications/db/notification.ex b/lib/notifications/db/notification.ex
index 24c03f7cb..8141e5c88 100644
--- a/lib/notifications/db/notification.ex
+++ b/lib/notifications/db/notification.ex
@@ -1,5 +1,7 @@
 defmodule Notifications.Db.Notification do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `notifications` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/notifications/db/notification_user.ex b/lib/notifications/db/notification_user.ex
index 3ccfcfb55..df1f9305d 100644
--- a/lib/notifications/db/notification_user.ex
+++ b/lib/notifications/db/notification_user.ex
@@ -1,5 +1,7 @@
 defmodule Notifications.Db.NotificationUser do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `notification_users` Database table
+  """
 
   use Skate.Schema
 
diff --git a/lib/skate/detours/db/detour.ex b/lib/skate/detours/db/detour.ex
index 6cf3ca5b5..72f51f116 100644
--- a/lib/skate/detours/db/detour.ex
+++ b/lib/skate/detours/db/detour.ex
@@ -1,5 +1,7 @@
 defmodule Skate.Detours.Db.Detour do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `detours` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/skate/settings/db/route_tab.ex b/lib/skate/settings/db/route_tab.ex
index 5c72eb74e..ad9d7321d 100644
--- a/lib/skate/settings/db/route_tab.ex
+++ b/lib/skate/settings/db/route_tab.ex
@@ -1,5 +1,7 @@
 defmodule Skate.Settings.Db.RouteTab do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `route_tabs` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/skate/settings/db/test_group.ex b/lib/skate/settings/db/test_group.ex
index fa4c9c0ce..e2236dcb1 100644
--- a/lib/skate/settings/db/test_group.ex
+++ b/lib/skate/settings/db/test_group.ex
@@ -1,5 +1,7 @@
 defmodule Skate.Settings.Db.TestGroup do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `test_groups` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/skate/settings/db/test_group_user.ex b/lib/skate/settings/db/test_group_user.ex
index dcb86c85f..f045ca4e8 100644
--- a/lib/skate/settings/db/test_group_user.ex
+++ b/lib/skate/settings/db/test_group_user.ex
@@ -1,5 +1,7 @@
 defmodule Skate.Settings.Db.TestGroupUser do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `test_groups_users` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/skate/settings/db/user.ex b/lib/skate/settings/db/user.ex
index 76b7fe625..185698b42 100644
--- a/lib/skate/settings/db/user.ex
+++ b/lib/skate/settings/db/user.ex
@@ -1,5 +1,7 @@
 defmodule Skate.Settings.Db.User do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `users` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset
diff --git a/lib/skate/settings/db/user_settings.ex b/lib/skate/settings/db/user_settings.ex
index 9f2c69cf4..bc5a7c9dd 100644
--- a/lib/skate/settings/db/user_settings.ex
+++ b/lib/skate/settings/db/user_settings.ex
@@ -1,5 +1,7 @@
 defmodule Skate.Settings.Db.UserSettings do
-  @moduledoc false
+  @moduledoc """
+  Ecto Model for `user_settings` Database table
+  """
 
   use Skate.Schema
   import Ecto.Changeset

From 5f1cef665b776d4f6b7eff3a1505b030cde831ec Mon Sep 17 00:00:00 2001
From: Kayla Firestack <kfirestack@mbta.com>
Date: Thu, 19 Sep 2024 18:05:19 -0400
Subject: [PATCH 2/3] feat:doc: group all Ecto models documentation

should make it easier to find our database related code, and easier to navigate in the documentation
---
 mix.exs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/mix.exs b/mix.exs
index cab488c0f..0cb7c28fe 100644
--- a/mix.exs
+++ b/mix.exs
@@ -15,10 +15,18 @@ defmodule Skate.MixProject do
       consolidate_protocols: Mix.env() != :test,
       dialyzer: [
         plt_add_apps: [:mix]
-      ]
+      ],
+      docs: docs_config()
     ]
   end
 
+  def docs_config,
+    do: [
+      groups_for_modules: [
+        "Ecto Schemas": &(&1[:section] == :ecto)
+      ]
+    ]
+
   # Configuration for the OTP application.
   #
   # Type `mix help compile.app` for more information.

From 8d226f3b1c79fa7dd39817e15d83c45b463e2b89 Mon Sep 17 00:00:00 2001
From: Kayla Firestack <kfirestack@mbta.com>
Date: Tue, 24 Sep 2024 12:23:56 -0400
Subject: [PATCH 3/3] feat: do `@module_doc section: :ecto` in schema

---
 lib/skate/schema.ex | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/skate/schema.ex b/lib/skate/schema.ex
index d18c8b83e..3b4cb8c27 100644
--- a/lib/skate/schema.ex
+++ b/lib/skate/schema.ex
@@ -5,6 +5,8 @@ defmodule Skate.Schema do
 
   defmacro __using__(_opts) do
     quote do
+      @moduledoc section: :ecto
+
       use TypedEctoSchema
     end
   end