feat:doc: stub doc headers for database tables

[firestack]

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.

I've also created a ExDoc group which is enabled via setting the option on @moduledoc section: :ecto, this should make it easier to find our database related code, and easier to navigate in the documentation.

---

It is possible to do this automatically for Ecto schemas, by setting this attribute in the shared Skate.Schema module. I do think this is neat, but I'm not really certain(i.e., let's discuss) this is a good decision?

diff --git a/lib/skate/schema.ex b/lib/skate/schema.ex
index d18c8b83e3..cde6e814cd 100644
--- a/lib/skate/schema.ex
+++ b/lib/skate/schema.ex
@@ -5,6 +5,8 @@
 
   defmacro __using__(_opts) do
     quote do
+      @module_doc section: :ecto
+
       use TypedEctoSchema
     end
   end

I like that this means we don't need to remember to add section: :ecto to all new Ecto schemas, because we have a growing list of "conventions" which are difficult to keep all in your head. But on the other hand, putting the @module_doc in the schema macro removes the choice later to easily change the section: :ecto value, I looked into making the @module_doc setting conditional, but wasn't very successful on my first attempt.

[github-actions]

Coverage of commit 4475743

Summary coverage rate:
  lines......: 92.5% (3302 of 3568 lines)
  functions..: 71.8% (1365 of 1901 functions)
  branches...: no data found

Files changed coverage rate:
                                                                  |Lines       |Functions  |Branches    
  Filename                                                        |Rate     Num|Rate    Num|Rate     Num
  ======================================================================================================
  lib/notifications/db/block_waiver.ex                            |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/bridge_movement.ex                         |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/notification.ex                            |66.7%      6|77.8%     9|    -      0
  lib/notifications/db/notification_user.ex                       | 100%      1|80.0%     5|    -      0
  lib/skate/detours/db/detour.ex                                  | 100%      2| 100%     6|    -      0
  lib/skate/settings/db/route_tab.ex                              |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group.ex                             | 100%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group_user.ex                        |66.7%      3|71.4%     7|    -      0
  lib/skate/settings/db/user.ex                                   |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/user_settings.ex                          |66.7%      3|85.7%     7|    -      0

Download coverage report

[github-actions]

Coverage of commit 13cbc8f

Summary coverage rate:
  lines......: 92.5% (3310 of 3580 lines)
  functions..: 71.4% (1366 of 1912 functions)
  branches...: no data found

Files changed coverage rate:
                                                                  |Lines       |Functions  |Branches    
  Filename                                                        |Rate     Num|Rate    Num|Rate     Num
  ======================================================================================================
  lib/notifications/db/block_waiver.ex                            |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/bridge_movement.ex                         |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/notification.ex                            |66.7%      6|77.8%     9|    -      0
  lib/notifications/db/notification_user.ex                       | 100%      1|80.0%     5|    -      0
  lib/skate/detours/db/detour.ex                                  | 100%      2| 100%     6|    -      0
  lib/skate/settings/db/route_tab.ex                              |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group.ex                             | 100%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group_user.ex                        |66.7%      3|71.4%     7|    -      0
  lib/skate/settings/db/user.ex                                   |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/user_settings.ex                          |66.7%      3|85.7%     7|    -      0

Download coverage report

[joshlarson]

@firestack

But on the other hand, putting the @module_doc in the schema macro removes the choice later to easily change the section: :ecto value, I looked into making the @module_doc setting conditional, but wasn't very successful on my first attempt.

I'm not worried about this. If it turns out to be a problem later on, we can remove it from the __using__ section in schema and put it somewhere else.

[joshlarson]

I went back and forth because the generated docs are pretty sparse. But you did advertise these as stubs, and they do have the potential to fix some broken links.

I'm good with this as-is. I'm also good with you updating the macro itself as you suggested in the PR description.

[github-actions]

Coverage of commit 8d226f3

Summary coverage rate:
  lines......: 92.5% (3310 of 3580 lines)
  functions..: 71.4% (1366 of 1912 functions)
  branches...: no data found

Files changed coverage rate:
                                                                  |Lines       |Functions  |Branches    
  Filename                                                        |Rate     Num|Rate    Num|Rate     Num
  ======================================================================================================
  lib/notifications/db/block_waiver.ex                            |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/bridge_movement.ex                         |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/notification.ex                            |66.7%      6|77.8%     9|    -      0
  lib/notifications/db/notification_user.ex                       | 100%      1|80.0%     5|    -      0
  lib/skate/detours/db/detour.ex                                  | 100%      2| 100%     6|    -      0
  lib/skate/settings/db/route_tab.ex                              |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group.ex                             | 100%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group_user.ex                        |66.7%      3|71.4%     7|    -      0
  lib/skate/settings/db/user.ex                                   |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/user_settings.ex                          |66.7%      3|85.7%     7|    -      0

Download coverage report

[github-actions]

Coverage of commit 8d226f3

Summary coverage rate:
  lines......: 92.5% (3310 of 3580 lines)
  functions..: 71.4% (1366 of 1912 functions)
  branches...: no data found

Files changed coverage rate:
                                                                  |Lines       |Functions  |Branches    
  Filename                                                        |Rate     Num|Rate    Num|Rate     Num
  ======================================================================================================
  lib/notifications/db/block_waiver.ex                            |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/bridge_movement.ex                         |66.7%      3|71.4%     7|    -      0
  lib/notifications/db/notification.ex                            |66.7%      6|77.8%     9|    -      0
  lib/notifications/db/notification_user.ex                       | 100%      1|80.0%     5|    -      0
  lib/skate/detours/db/detour.ex                                  | 100%      2| 100%     6|    -      0
  lib/skate/settings/db/route_tab.ex                              |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group.ex                             | 100%      3|85.7%     7|    -      0
  lib/skate/settings/db/test_group_user.ex                        |66.7%      3|71.4%     7|    -      0
  lib/skate/settings/db/user.ex                                   |66.7%      3|85.7%     7|    -      0
  lib/skate/settings/db/user_settings.ex                          |66.7%      3|85.7%     7|    -      0

Download coverage report