I have been thinking some more and would like to revise my proposal. The *Modules > Alphabetical* and *Categories > Modules > Alphabetical* navigation trees handle distinct use cases.
*Modules Case:* when a developer knows the module AND the function one is looking for (e.g. when referencing the documentation for debugging). *Categories Case:* when a developer is about to write some logic and wants to see whether it exists in the core already. The pitfall of *Modules*-first navigation is when you don't know the module NOR the function, you must scour the documentation by brute force. When you don't know the module, you can type the function in the search bar, but that's more keystrokes than brute force navigation. Put another way, the problem is *Modules-first navigation isn't heuristic enough.* A paradigmatic example is not knowing whether you'll find a given function in `List` or `Enum`. By contrast, *Categories*-first navigation is significantly more heuristic because while many modules share common functionality-- e.g. `Kernel.to_string/1`, `Atom.to_string/1`, and `Integer.to_string/1` `Kernel.to_string/1` <https://hexdocs.pm/elixir/Kernel.html#to_string/1> works for any type by implementing the `String.Chars` protocol <https://hexdocs.pm/elixir/String.Chars.html>, which calls `Atom.to_string/1` if it receives an atom <https://github.com/elixir-lang/elixir/blob/v1.7.3/lib/elixir/lib/string/chars.ex#L25>, `Integer.to_string/1` if it receives an integer <https://github.com/elixir-lang/elixir/blob/v1.7.3/lib/elixir/lib/string/chars.ex#L52>, etc. --the category *is defined by what modules share* in common, making them *mutually exclusive*--i.e. you'll find `Kernel.to_string/1`, `Atom.to_string/1`, and `Integer.to_string/1` all in the same place (ordered by category, then module, then alphabetically). BTW, Elixir's module groupings are first by *category* THEN alphabetically: Kernel + Kernel.SpecialForms, BASIC TYPES, COLLECTIONS & ENUMERABLES, IO & SYSTEM, MODULES & CODE, PROCESSES & APPLICATIONS, PROTOCOLS, DEPRECATED. The implementation I'm proposing for :ex_doc is *`@groups categories :: [atom] \\ []`* and *`@category metadata :: [name: atom, description: String.t \\ "", rank: pos_integer \\ 1, include: modules :: [atom] \\ [] ]`* . `@groups` is a function-level tag. It accepts a list of category names *(atoms)*, defined with `@category`. `@category` is a module-level tag that accepts a keyword list. It requires a unique name *(an atom)*. It accepts a description *(just like a string for `@moduledoc`, while allowing more flexible groupings)*, a rank *(allowing for custom navigation trees)*, and an `:include` option *(which automatically prepends the category to all functions' `@groups` list within the listed modules)*. Instead of pages being generated by module (the default), they can be generated by `@groups` with custom-defined and -ranked `@category` tags, giving the developer greater control over how one's library is documented. For Elixir's documentation, you'd have the ability to A/B test a *Categories*-first navigation tree via a new CATEGORIES tab: Regardless of whether the community leans towards a *Modules*-first navigation tree or keeping both, this feature is good for :ex_doc. And these tags can still be leveraged as I originally proposed: as an advanced search feature. On Friday, September 14, 2018 at 12:59:52 PM UTC-7, Alexander Marks-Katz wrote: > > Okay: > https://github.com/elixir-lang/ex_doc/pull/879#issuecomment-411102276 > > So tags is its own thing. > > I guess I'll take a look at how `:since` works & see what I can do for a > searchable `:category` *tag*. > > English3000.org: *A data-driven approach to language learning.* > > > On Fri, Sep 14, 2018 at 11:01 AM José Valim < > jose.va...@plataformatec.com.br> wrote: > >> His implementation is correct. It is about categories, not tags. A >> certain entry can only belongs to a single category. >> -- >> >> >> *José Valim* >> www.plataformatec.com.br >> Skype: jv.ptec >> Founder and Director of R&D >> >> -- >> You received this message because you are subscribed to a topic in the >> Google Groups "elixir-lang-core" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/elixir-lang-core/TxDvKFwltZU/unsubscribe >> . >> To unsubscribe from this group and all its topics, send an email to >> elixir-lang-core+unsubscr...@googlegroups.com. >> To view this discussion on the web visit >> https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4LYjO6NC18OAhn9BmzXqohB-41egfj9AT0SJ_9RwsACbQ%40mail.gmail.com >> >> <https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4LYjO6NC18OAhn9BmzXqohB-41egfj9AT0SJ_9RwsACbQ%40mail.gmail.com?utm_medium=email&utm_source=footer> >> . >> For more options, visit https://groups.google.com/d/optout. >> > -- You received this message because you are subscribed to the Google Groups "elixir-lang-core" group. To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/f299d4e7-4910-43d7-963d-1f8da013e69f%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
