Ex_doc: Remove the distinction between functions and macros from the sidebar

Created on 21 Nov 2016  路  3Comments  路  Source: elixir-lang/ex_doc

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.

Enhancement Discussion

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.

All 3 comments

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!

Was this page helpful?
0 / 5 - 0 ratings

Related issues

zacky1972 picture zacky1972  路  4Comments

eksperimental picture eksperimental  路  4Comments

fertapric picture fertapric  路  10Comments

akrisanov picture akrisanov  路  8Comments

ericmj picture ericmj  路  8Comments