Arbitrary grouping of functions with `@doc group: :some_group`

[lackac]

The new documentation metadata and specifically the @doc keyword() construct opens up new possibilities for enriching the ExDoc UI and providing better ways to navigate and explore.

ExDoc is already making use of the guard: true metadata to group guards together in Kernel and other modules. It could similarly allow arbitrary grouping of functions:

defmodule Flow do
  @doc group: :mappers
  def each(flow, each)

  @doc group: :mappers
  def filter(flow, filter)

  @doc group: :reducers
  def reduce(flow, acc_fun, reducer_fun)

  @doc group: :reducers
  def group_by(flow, key_fun, value_fun)
end

The code above would instruct ExDoc to create two new groups in the sidebar: "Mappers" and "Reducers". The same grouping would also be used on the main content side. The behaviour would be exactly the same as the existing "Callbacks" and "Types" grouping. Optionally we could also introduce a way to toggle grouping.

This is mostly useful for modules that define a high number of functions where separating them conceptually would provide a better experience for the reader. (e.g. documentation of Flow, or some ExAws packages with larger footprints)

Some details of how this would behave still needs to be worked out and can be discussed if this finds support.

[josevalim]

I like this, although some people had reservations around groups. /cc @ericmj @benwilson512 @michalmuskala

[josevalim]

@lackac btw, it may be better to have a bit of indirection here and allow groups to be created based on the metadata. This means that we would do:

@doc mapper: true
@doc reducer: true

Or

@doc flow_type: :mapper

And then we tell ExDoc how to build this:

groups_for_functions: %{
  Mappers: & &1[:flow_type] == :mapper
}

Similar approach could be done for groups_for_modules. But in the groups_for_modules case I like that all information is in a single place (the mix.exs). This is much harder to do for functions.

[benwilson512]

I like this idea. A good example would be ExAws.S3 which has a reasonably large surface area, and the main AWS docs categorize the actions into "Actions on Buckets", "Actions on Objects" etc. Being able to reproduce that structure in ExDoc would definitely improve the doc experience.

[lackac]

@josevalim I like the idea of adding an extra indirection. It leaves area for flexibility to make the code more descriptive.

…

On 2018. Jul 24., Tue at 12:36, José Valim ***@***.***> wrote: @lackac <https://github.com/lackac> btw, it may be better to have a bit of indirection here and allow groups to be created based on the metadata. This means that we would do: @doc mapper: true @doc reducer: true Or @doc flow_type: :mapper And then we tell ExDoc how to build this: groups_for_functions: %{ Mappers: & &1[:flow_type] == :mapper } Similar approach could be done for groups_for_modules. But in the groups_for_modules case I like that all information is in a single place (the mix.exs). This is much harder to do for functions. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#876 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAFSCoKTscgd0CUyMWVa-Hntf_JP3ODks5uJvjIgaJpZM4Vb4io> .

[josevalim]

I think we can go ahead with this, since it will be a generic mechanism, we don't need to articulate with Elixir. I would even implement the Guards feature as a "default mapping" that we always add.

[lackac]

I wouldn't mind working on this, but I might not be able to get to it in the next couple weeks. In other words, don't wait on me if you prefer to have this sooner. :)

[josevalim]

No worries, take your time! There is no rush.

[English3000]

Just saw this issue, after posting this in the elixir-core group.

---

Also, I'd suggest along with guards, splitting macros off into their own dropdown.

---

And it appears you went with @josevalim's first suggestion atom => boolean rather than the second, atom => atom. The disadvantage of the former is when you want something to have multiple groups (atom => atom | [atom]). You can settle for a bunch of booleans, but I don't think this is the approach to take with attributes, as it will yield unwieldy code if implemented as a design pattern.

[English3000]

Also, I'd suggest along with guards, splitting macros off into their own dropdown.

[josevalim]

We had macros as their own dropdown and it caused more confusion than helped, as it made searching and finding functionality harder. I think grouping is generally useful but grouping too granularly can make accessibility worse in some cases. Other projects can group macros if they want to, but we don't plan to do so in Elixir.

[English3000]

I realize 'macros' is a bit vague. I mean the def*s (or, more generically, reserved keywords that are macros). If it doesn't cause a hassle, they could be moved to Kernel.SpecialForms

If you still disagree, could you link me to the thread(s) you are referring to?

[josevalim]

def and friends in Elixir are not keywords. They are just regular macros. They are also not special forms because special forms are special macros implemented by the compiler.