Provide function group descriptions in Ecto.Repo

[rhcarvalho]

• Add descriptions to "Query API", "Schema API", etc.
• Move Ecto.Repo.all_running/0 to "Process API" group.

---

I was reading the docs for update_all and was surprised to find it under "Query API", while other update-related callback functions are part of the "Schema API".

I understand "Query API" is for all APIs related to reading from the database, and "Schema API" for writing. In that interpretation, load, reload, reload!, and preload would also fit better within Query API.
Update: the groups are based on the data they operate on, see #4643 (comment).

The all_running/0 function was the only one outside any group, but it fits with the "Process API" group.

[josevalim]

Query API receives an Ecto.Query, while the Schema API receives an schema. Perhaps we should make it clearer? New ExDoc versions allows us to add descriptions to each group, perhaps we should use that. And yes, Process API group is perfect.

[rhcarvalho]

Query API receives an Ecto.Query, while the Schema API receives an schema.

Aha, I see, under this definition it makes sense that update_all and update are separate.

New ExDoc versions allows us to add descriptions to each group, perhaps we should use that.

I'll look into it.

[rhcarvalho]

New ExDoc versions allows us to add descriptions to each group, perhaps we should use that.

I found how to do it in ex_doc main https://github.com/elixir-lang/ex_doc/blame/3ebc1daa20f8aa54f53e15f5da6d7c1559ec64ea/lib/mix/tasks/docs.ex#L368-L382, but it is not yet released.

Latest release: https://hexdocs.pm/ex_doc/0.38.2/Mix.Tasks.Docs.html#module-grouping-functions-types-and-callbacks

References:

• Defining a text bloc for group_for_docs sections elixir-lang/ex_doc#2104
• Display description text in docs groups elixir-lang/ex_doc#2113

---

Changes:

• I've updated the patch to only move all_running/0 from no group to "Process API", reverting other changes/moves that do not make sense according to what each group was meant for.
• Bumped ex_doc (picking up from main) to use @moduledoc groups: instead of groups_for_docs

Looks like this:

I wonder if we should hold off until a new release of ExDoc?

[josevalim]

💚 💙 💜 💛 ❤️