Add group metadata to EEP48

[josevalim]

Also changed one item to keep order alphabetical.

For ExDoc, I propose that, if the group is used, it will still be prefixed by its type, such as "Functions" or "Types". For example, in Nx, you can imagine the functions below were tagged as: group: "Aggregates", group: "Backend", etc.

However, if you really want to override it, you can use the groups_for_docs configuration. Like done above, where "Guards" are getting its own group.

@garazdawi would these conventions suit Erlang?

[github-actions]

CT Test Results

    2 files     70 suites   1h 7m 28s ⏱️
1 563 tests 1 321 ✅ 242 💤 0 ❌
1 813 runs  1 521 ✅ 292 💤 0 ❌

Results for commit ffc7372.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

• Complete CT logs (Download Logs)
• HTML Documentation (Download HTML Docs)
• Windows Installer

// Erlang/OTP Github Action Bot

[garazdawi]

Yes, using group for grouping works great. I however have some opinions on what ExDoc should do with this data.

The way that I did for us was like this:

1. Function groups are placed before the general "Functions", but after the "Callbacks". I like it this way as you get a logical ordering of things. Especially when all fuctions end up in some group, but all types do not.
2. Types and callbacks get a prefix, functions do not. I think this makes sense as I would expect groups to be mainly used for functions + types, and the string "Functions" is a lot longer than "Types". I did have the "Functions:" prefix when I started, but found that it created very long group names and did not add that much if the ordering was done as described above.

For an examples see ssl, ssh and string.

The code that does this lives here and I even wrote some docs.

[josevalim]

@garazdawi I see. I'd prefer to have one single and clear rule, so we either add "Type: " and "Function: " or we never add it. Then we can possibly add a new callback in ExDoc that configures the :default_group. This way, if we assume we start without it, you could do this:

default_group: fn metadata ->
  case metadata do
    %{group: group, kind: :type} -> "Types: #{group}"
    _ -> nil
  end
end

So it is easy for you to convert from one default to another.

I think this default_group idea would make your life easier anyway. :)

[garazdawi]

Sure, a simple rule makes sense. I don't mind either way as the default.

I still think the ordering is important, so that function groups are always below the types + callback.

[josevalim]

I don't have any opinion or reservations on the ordering, so I am glad to defer to your preference. :)

[garazdawi]

I just realised that the reference manual should also be updated, so I pushed a fixup commit. Feel free to squash if you agree and I'll merge this.

[josevalim]

I have been thinking a bit more about this from the shell side. When can we realistically use groups?

We can definitely autocomplete a remote call and, in that case, looking up the docs chunk is necessary to avoid showing private functions, so we can get the group.

However, would we show group for any local or import auto completion? Because those can come from several modules and they have already been imported anyway, I would say no?

Also, should we show group for modules? That would require getting the docs chunk for every module, which is potentially too expensive. So we should show groups there.

Are those ok?

Also, groups in ExDoc have historically been atoms, but binary strings are likely better. So I would have to change this there internally too.

[garazdawi]

I was thinking mainly for function completion. That is when you do:

1> string:<TAB>
Functions:
casefold(             chomp(              concat(             .....
Obsolete API Functions
centre(               chars(....

I think that would be the primary usecase. We can add more later on if we like, though for ExDoc it might be good to have ground for modules already now as you can use those already.

However, would we show group for any local or import auto completion? Because those can come from several modules and they have already been imported anyway, I would say no?

Not sure what you mean by this, if you mean functions defined in the shell session, at least we have a separate group for those already.

Also, groups in ExDoc have historically been atoms, but binary strings are likely better. So I would have to change this there internally too.

I think they can be binary strings already? or am I missing something?

[josevalim]

Not sure what you mean by this, if you mean functions defined in the shell session, at least we have a separate group for those already.

The ones defined in the shell OR imported, such as is_atom/1 and many others in erlang.

I think they can be binary strings already? or am I missing something?

Theoretically they cannot but it may just work today. :D

[garazdawi]

What do you think @frazze-jobb? does this make sense for the shell?

[frazze-jobb]

I like the idea.
When it comes to deprecated or private functions I would rather not show them by default. Unless explicitly set to show them with a keypress, or configuration option.
Function grouping in general, would probably clutter up the display.
So only show them in full-expand.

nx:<tab><tab>
Functions: (maybe can be omitted)
Aggregate:
A
B
C
Backend: 
D
E
F
Conversion: 
G
H
I
----Show more----

Its already cluttered as it is when you just type:

i<tab>

I think it could make more sense with additional keys in expand mode to toggle sorting methods, and more navigation keys/or search to quickly jump to a certain group and select the function of interest.
Instead of the traditional method where you would need to read the expand display and then type the prefix of the function you want, press <tab> and then repeat the process in case of ambiguity with functions in other groups.

I'm also contemplating if we should support fuzzy matching of a function, but thats a topic for another day.

[garazdawi]

When it comes to deprecated or private functions I would rather not show them by default.

Yes for deprecated, but I think that the shell should be considered a debug tool which should expose "-doc false" functions.

Function grouping in general, would probably clutter up the display. So only show them in full-expand.

Yes, agreed, but right now edlin_expand does not have information about whether we are doing a <tab> or a <tab><tab>, so any filtering would need to be done by edlin/group, so it would need to strip all groups on <tab> which might actually be a good idea. It would of course also be quite trivial to add an option to edlin_expand that tells it whether it is a single or double tab.

[garazdawi]

I squashed the changes and merged for release in Erlang/OTP 28. Thanks!

[josevalim]

Thank you! I have finished the changes to ExDoc, I will implement Group in the terminal today and report back.

[josevalim]

Ok, I have implemented it all works well. Let me know if you need further changes in ExDoc. If we can all use group, then it means Erlang groups will automatically appear when we autocomplete Erlang modules from Elixir and vice-versa.