Defining a text bloc for group_for_docs sections

[lud]

Hello,

I would like to know if it is currently possible to inject some text in the generated docs below the section headers that are generated from groups_for_docs.

If not, is this something you'd consider adding?

Thank you.

[josevalim]

Just to make sure we are on the same page, can you send a screenshot showing where you'd want to add the text?

[garazdawi]

If I understand the request correctly, this is something that we would also like to have in our docs. That is the possibility to add some text below this heading: https://www.erlang.org/doc/apps/stdlib/string.html#obsolete-api-functions

[josevalim]

In that case, a PR is definitely welcome.

[lud]

Yes, exactly here.

Below the "Schema Definition Utilities" header, that is a section header after the Summary section with signatures.

In that case, a PR is definitely welcome.

I'll give it a try. Any direction or general rule to consider before starting?

[josevalim]

I'll give it a try. Any direction or general rule to consider before starting?

No, go for it!

[garazdawi]

Any direction or general rule to consider before starting?

As it is now possible to create groups via two mechanism, that is doc metadata and configuration file, IMO it should also be possible to add the "group description" with those two mechanisms. The syntax for writing the description should IMO be markdown (and not just text as deprections are), so that we can have links and other things in there.

[lud]

To me the groups are defined like so:

  defp groups_for_docs do
    [
      "Helpers": &(&1[:section] == :helpers)
    ]
  end

Or a catchall

default_group_for_doc: fn metadata ->
  if group = metadata[:group] do
    "Functions: #{group}"
  end
end

In both cases you can return a binary like :"Helpers" or a binary like "Functions: some group".

Are you mentioning another mechanism?

I feel like the markdown should be attached to that returned value, and not metadata in the module file, because instead of &1[:section] == :helpers you could match on other metadata entries. The :section key is nothing special. (The :group is though, but just because it's a default).

So in this example, the markdown should be retrieved from the :"Helpers" key. That could be yet another callback for mix.exs / project / :docs like this:

description_for_group: fn
  :"Helpers" -> 
    """
    Hello world....

    * hello
    * goodbye
    """
  _ -> 
    nil
end

But admitedly this is a lot of indirection.

We could pass the module too:

description_for_module_group: fn
  module, :"Helpers" -> 
    """
    Hello world....

    * hello
    * goodbye
    """
  _, _ -> 
    nil
end

Which would allow us to provide a default implementation:

description_for_module_group: fn module, section_header -> 
  case Code.fetch_docs(module) do
    {:docs_v1, _, _, _, _, %{^section_header => doctext}, _} -> doctext
    _ -> nil
end

Which would finally make it possible to define the doc like this:

defmodule SomeModule do
  @moduledoc """
  The real module doc
  """
  
  @moduledoc "Helpers": """
    Hello world....

    * hello
    * goodbye
  """
end

What do you think about this?

[josevalim]

I think you covered the options well but all of them come with trade-offs that I am not particularly excited about. Storing it as metadata in the moduledoc can be interesting, so we can keep all of the markup in one place, but you can also have reused groups (and perhaps reused descriptions).

[lud]

If you want to reuse I guess instead of using the defaults, you provide :description_for_module_group like this:

description_for_module_group: fn
  _module, :"Helpers" -> MyApp.Docs.description_for(:"Helpers")
  _module, :"Deprecated" -> """
    Some old stuff..
    """
  _, _ -> nil
end

I think it's possible to call app code from mix.exs right? As it is evaluated by a mix task.

[josevalim]

Yes, still a lot of indirection (as you said).

[lud]

Yes.

We could take shortcuts:

If groups_for_docs returns iodata then it's a match and the text is going to be used as the description. If it returns true, false or nil it behaves as usual (no description).

defp groups_for_docs do
  [
    Helpers:
      &(&1[:section] == :helpers &&
          """
          Some docs here
          """),
    Deprecations: &(&1[:section] == :old_stuff)
  ]
end

In the catchall you can return a {header, text} tuple, or a text/nil as usual.

default_group_for_doc: fn metadata ->
  case metadata[:section] do
    :helpers ->
      {"Helpers",
        """
        Some docs here
        """}

    :old_stuff ->
      "Deprecations"

    _ ->
      nil
  end
end

Less indirection, but no support for per-module text (but there is no support for per module header currently. I guess people just use different section names for different modules as I do), and possible weird syntax:

# Big chunk of text in the middle of a function
:helpers ->
    {"Helpers",
      """
      Some docs here
      """}

# Big chunk of text in mix.exs
:helpers ->
    {"Helpers", @helpers_doctext}

# Indirection strikes back
:helpers ->
    {"Helpers", MyApp.Docs.helpers_description()}     

[josevalim]

Oh, I like this direction. Let's start with default_group_for_doc, as it is the most general form, and allow it to return either: "Title" or [title: "Title", description: "some markdown"]? Would this work for you @garazdawi?

[garazdawi]

What I would like to be able to do in the end is what was proposed by @lub above:

defmodule SomeModule do
@moduledoc """
 The real module doc
 """
 
 @moduledoc "Helpers": """
   Hello world....

   * hello
   * goodbye
 """
end

I want to keep both the group titles and descriptions in the file that we are documenting and not in the config file for the application. Would that be possible with this approach?

Are you mentioning another mechanism?

What I meant was the default_group_for_docs + group_for_docs.

[josevalim]

I want to keep both the group titles and descriptions in the file that we are documenting and not in the config file for the application. Would that be possible with this approach?

I don't think so because we only receive the function metadata and not the module one. :( We could perhaps change it to pass both but I am not convinced.

About your approach, I am worried about polluting the .beam files with metadata which is ultimately for the docs generation and likely won't be used by any other documentation tooling (such as IDEs, terminal, etc). Thoughts? Perhaps if we want it to be used consistently, it should be an "update" to EEP 48?

[garazdawi]

For groups we already use the metadata in the terminal to group things visually, I don't see it as very unlikely that it should be used also to display that text. And yes, I suppose in that case it would be an extension to EEP-48 as well.

I get the need for not pushing too much stuff into the doc metadata, but as the groups are already there, to me it feel natural to also have this.