quote as entry breaks the face of a macro inside terminal

[shahryarjb]

I hope that I have not reported a duplicate problem and that I have posted the issue in the right place

When we use quote in the entry of a macro. In the terminal, if we put h behind it. Its shape is broken.
For example, this can be seen in the dbg document

defmacro dbg(code \\ quote(do: binding()), options \\ []) do

Image

Other macro:

Thank you in advance

[dinocosta]

@josevalim Would you mind me taking a look at this one? Not sure how hard this would be to solve but I'd like to try it :)

[josevalim]

Yes, please go ahead! :)

[dinocosta]

After some investigation it seems that the issue might be caused at compilation time, when generating the documentation for the .beam file of the corresponding module.

I say this because, it seems like, simply loading the documentation from the .beam file returns the function's signature with newline characters:

iex(1)> docs_chunk = [?D, ?o, ?c, ?s]
...
iex(2)> {_module, bin, filename} = :code.get_object_code(Kernel)
...
iex(3)> {:ok, {_module, [{_docs_chunk, bin}]}} = :beam_lib.chunks(bin, [docs_chunk])
...
iex(4)> {:docs_v1, _, _, _, _, _, docs} = :erlang.binary_to_term(bin)
...
iex(5)> {{:macro, :dbg, 2}, _, signature, _, _} = Enum.find(docs, fn {{_, name, _}, _, _, _, _} -> name == :dbg end)
...
iex(6)> IO.inspect(signature)
["dbg(code \\\\ quote do\n  binding()\nend, options \\\\ [])"]

Worth noting I'm not super familiar with the specifics on this part, so my assumption might be totally wrong but I'm going to try and understand how the documentation for the function signature is generated for the .beam file, maybe some of the characters (or combination of characters) in Kernel.dbg's signature are getting converted to newline characters (\n).

Will report once I have more findings 🔍

[josevalim]

I think it is ok for the signature to have multiple lines, we just need to align the background when printing it in the terminal. :)

[dinocosta]

Thanks @josevalim !

I've managed to get it to print the following by simply splitting the headings, in IO.ANSI.Docs.print_headings/2, by newline character:

Does this look good to you? I'm thinking that maybe, in cases where the heading has newline characters we should try and align it according to the first line, keeping the indentation correct, instead of centering horizontally, like this:

                         defmacro dbg(code \\ quote do                          
                           binding()                                   
                         end, options \\ [])                               

What do you think? :)

[josevalim]

Looks great. I would align it as:

                         defmacro dbg(code \\ quote do                          
                                    binding()                                   
                                  end, options \\ [])     

[dinocosta]

Awesome, thank you for the feedback @josevalim ! I'll open a PR shortly so you can review and see if my approach makes sense ⭐️

[dinocosta]

@josevalim Here it is - #13018 ✅

[shahryarjb]

Looks great. I would align it as:

                         defmacro dbg(code \\ quote do                          
                                    binding()                                   
                                  end, options \\ [])     

Why can't we fill the whole width? and keep this line in one line not break it
@josevalim @dinocosta