Today we split entries between functions and macros which is not useful for discoverability. If I am learning a new API, I typically do not care if something is a macro or a function.
I propose to remove the distinction between functions and macros from the sidebar and use the tag to mark macros as macros. The tag works similar to here:
http://elixir-lang.org/docs/master/elixir/GenServer.html#c:format_status/2
Notice the "(optional)" tag on the right-hand side.
I took at shot at this in #653, and I'm happy with the results. Discovery definitely feels improved. The only negative aspect of the change that I've experienced so far is that, for some complex modules (e.g. Kernel), the function list is now quite long. I suspect that's atypical, however, and says more about how the module is organized and less about the ratio of exported macros vs functions.
We are keeping this one open because we removed the distinction between Functions / Macros from the sidebar but we should find a way to make it slightly more obvious that something is a macro in the full listing.
This has been done!
Most helpful comment
We are keeping this one open because we removed the distinction between Functions / Macros from the sidebar but we should find a way to make it slightly more obvious that something is a macro in the full listing.