[Proposal] Add tags to Elixir core functions

69 views
Skip to first unread message

english...@gmail.com

unread,
Sep 13, 2018, 10:47:19 PM9/13/18
to elixir-lang-core
Just as we can tag discussions on Elixir Forum, making them more searchable, Elixir core's functions should be tagged.

This will make the Hex docs significantly more beginner-friendly and will give the core team a more systematic way to track the size and scope of the kernel.

`@doc` could accept a `:category` tag (I've made a repo [in progress] categorizing the more commonly used functions from the basic data structure modules).

To make tags even more powerful, you can add an `:equivalents` (or `:delegates`) tag which would accept a list of functions that do the same thing or something very similar.

Sven Gehring

unread,
Sep 14, 2018, 4:38:03 AM9/14/18
to elixir-l...@googlegroups.com
I don't think forum discussions and function documentation can necessarily be compared.

If I understand the contents of the example repo right, you'd want to tag functions by the type of their arguments (e.g. which data structures they operate on).
This is largely already sorted by how they are organized in modules (Enum, String, etc.) I would go as far as saying those modules ARE categories of functions.

Adding an additional way of sorting the documentation would be more confusing than helpful in my opinion.
Personally, I also never had any issues finding functions, even when I started learning Elixir

--
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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/d370cbf9-92d0-4814-8332-54189634842e%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Alexander Marks-Katz

unread,
Sep 14, 2018, 12:52:16 PM9/14/18
to elixir-l...@googlegroups.com
No. Data structure-based modules already exist. I'm referring to `Conversions`, `Data`, `Operations`, etc. as tags.

To help you understand, I'm talking about differences between functions like how words have different parts of speech. I'm not talking about the difference between numbers and words.

Across all data structure modules, there are functions that specifically exist to convert that data structure to another. Making that distinct from other grouping/categories will make the documentation significantly more reasonable and allow newcomers to notice useful functions by grouping that they don't with an alphabetized list.

Point being, you wouldn't put a function for integers in the `String` module, so why would you put functions that convert data, operate on it, and give metadata on it all mixed together--as opposed to grouping them within the module.

English3000.org: A data-driven approach to language learning.


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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAFuVuxwMu3wh%3DC%2B2Lo2emziY%3DMZAucxXqUCrsMdTLrL3bL4bRQ%40mail.gmail.com.

Alexander Marks-Katz

unread,
Sep 14, 2018, 1:01:31 PM9/14/18
to elixir-l...@googlegroups.com
Also, this isn't a debate. The mechanism has already been implemented: https://github.com/elixir-lang/ex_doc/issues/876

English3000.org: A data-driven approach to language learning.

José Valim

unread,
Sep 14, 2018, 1:15:06 PM9/14/18
to elixir-l...@googlegroups.com
Well, it is definitely a debate because, although the mechanism is available we still need to debate:

1. if we will add the tags to Elixir
2. and then if we will include those categories in Elixir's own docs

Keep in mind the current categories implementation completely segregate functions in the sidebar, messing up the alphabetical ordering. And every time we messed up with the alphabetical ordering, people got really upset, as it made looking for a particular function (or something that you know exists but you are not quite sure about the name) much harder.

So my initial response is that we won't add more categories to Elixir itself unless we find another way to show them that doesn't mess with the alphabetical ordering in the documentation sidebar. Otherwise it will be just a matter of time before people ask us to remove the categories.





José Valim
Skype: jv.ptec
Founder and Director of R&D

On Fri, Sep 14, 2018 at 7:01 PM, Alexander Marks-Katz <english...@gmail.com> wrote:
Also, this isn't a debate. The mechanism has already been implemented: https://github.com/elixir-lang/ex_doc/issues/876

English3000.org: A data-driven approach to language learning.

On Fri, Sep 14, 2018 at 9:52 AM Alexander Marks-Katz <english...@gmail.com> wrote:
No. Data structure-based modules already exist. I'm referring to `Conversions`, `Data`, `Operations`, etc. as tags.

To help you understand, I'm talking about differences between functions like how words have different parts of speech. I'm not talking about the difference between numbers and words.

Across all data structure modules, there are functions that specifically exist to convert that data structure to another. Making that distinct from other grouping/categories will make the documentation significantly more reasonable and allow newcomers to notice useful functions by grouping that they don't with an alphabetized list.

Point being, you wouldn't put a function for integers in the `String` module, so why would you put functions that convert data, operate on it, and give metadata on it all mixed together--as opposed to grouping them within the module.

English3000.org: A data-driven approach to language learning.


On Fri, Sep 14, 2018 at 1:38 AM Sven Gehring <cbr...@gmail.com> wrote:
I don't think forum discussions and function documentation can necessarily be compared.

If I understand the contents of the example repo right, you'd want to tag functions by the type of their arguments (e.g. which data structures they operate on).
This is largely already sorted by how they are organized in modules (Enum, String, etc.) I would go as far as saying those modules ARE categories of functions.

Adding an additional way of sorting the documentation would be more confusing than helpful in my opinion.
Personally, I also never had any issues finding functions, even when I started learning Elixir

On Fri, 14 Sep 2018 at 04:47 <english...@gmail.com> wrote:
Just as we can tag discussions on Elixir Forum, making them more searchable, Elixir core's functions should be tagged.

This will make the Hex docs significantly more beginner-friendly and will give the core team a more systematic way to track the size and scope of the kernel.

`@doc` could accept a `:category` tag (I've made a repo [in progress] categorizing the more commonly used functions from the basic data structure modules).

To make tags even more powerful, you can add an `:equivalents` (or `:delegates`) tag which would accept a list of functions that do the same thing or something very similar.

--
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+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6RZHCC89TNF1YuWaEgCvRw1sDy%2BZWejBWfSeKreWMPhrQ%40mail.gmail.com.

Alexander Marks-Katz

unread,
Sep 14, 2018, 1:25:58 PM9/14/18
to elixir-l...@googlegroups.com
Ok, then display them like you display the `since` data.

And then add an advanced search feature (under the search bar) that leverages the tags to make functions show up by category.


English3000.org: A data-driven approach to language learning.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

--
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-co...@googlegroups.com.

--
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-co...@googlegroups.com.

--
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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2B%2BuSXj-L32qK9mdsMq-Lf6cCsAcKDtRqKzBa5%2B0QoGsA%40mail.gmail.com.

José Valim

unread,
Sep 14, 2018, 1:30:15 PM9/14/18
to elixir-l...@googlegroups.com
Yes, somebody needs to do this work in ExDoc though. Design the feature, propose and implement it. Once this is supported in ExDoc, then we can discuss the best way to leverage it from Elixir itself.



José Valim
Skype: jv.ptec
Founder and Director of R&D

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2B%2BuSXj-L32qK9mdsMq-Lf6cCsAcKDtRqKzBa5%2B0QoGsA%40mail.gmail.com.
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+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6Tadgkb7LBbmqYs73W0WSmxg_2vHNJffg%2BTRUY7bm3ROA%40mail.gmail.com.

Alexander Marks-Katz

unread,
Sep 14, 2018, 1:38:50 PM9/14/18
to elixir-l...@googlegroups.com

English3000.org: A data-driven approach to language learning.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

--
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-co...@googlegroups.com.

--
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-co...@googlegroups.com.

--
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-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2B%2BuSXj-L32qK9mdsMq-Lf6cCsAcKDtRqKzBa5%2B0QoGsA%40mail.gmail.com.
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-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6Tadgkb7LBbmqYs73W0WSmxg_2vHNJffg%2BTRUY7bm3ROA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JfqMQp3DuAdBGBaFwUrsoaq2wzqBj55SiCGhcF_YXEAA%40mail.gmail.com.

José Valim

unread,
Sep 14, 2018, 1:41:24 PM9/14/18
to elixir-l...@googlegroups.com
That pull request adds categories to the *sidebar*. But per my first comment, we are not going to adopt that style of sidebar organization to Elixir, at the level of granularity you propose, because it will cause confusing as it removes the alphabetical ordering. Other projects are free to adopt though if they feel it will be an improvement.



José Valim
Skype: jv.ptec
Founder and Director of R&D

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

--
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+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2B%2BuSXj-L32qK9mdsMq-Lf6cCsAcKDtRqKzBa5%2B0QoGsA%40mail.gmail.com.
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+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6Tadgkb7LBbmqYs73W0WSmxg_2vHNJffg%2BTRUY7bm3ROA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
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+unsubscribe@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JfqMQp3DuAdBGBaFwUrsoaq2wzqBj55SiCGhcF_YXEAA%40mail.gmail.com.
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+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6TyzGtdJ_GeKm%3DP0-Ae0tNZN2_%3DULuHWUy7XE6ESZcDDg%40mail.gmail.com.

Alexander Marks-Katz

unread,
Sep 14, 2018, 1:48:30 PM9/14/18
to elixir-l...@googlegroups.com
Okay. So then the tagging feature exists as lackac implemented it. However, the advanced search feature and `:category` metadata display (similar to how `:since` is displayed) do not.

As I disagree with how he implemented it as a design pattern (https://github.com/elixir-lang/ex_doc/issues/876#issuecomment-421423919), were I to work on this, I'd try to implement `category: atom | [atom]` (as opposed to the current implementation `atom => boolean`).

How does that sound?

English3000.org: A data-driven approach to language learning.

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

--
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-co...@googlegroups.com.

--
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-co...@googlegroups.com.

--
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-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2B%2BuSXj-L32qK9mdsMq-Lf6cCsAcKDtRqKzBa5%2B0QoGsA%40mail.gmail.com.
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-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6Tadgkb7LBbmqYs73W0WSmxg_2vHNJffg%2BTRUY7bm3ROA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
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-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JfqMQp3DuAdBGBaFwUrsoaq2wzqBj55SiCGhcF_YXEAA%40mail.gmail.com.
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-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAF9bs6TyzGtdJ_GeKm%3DP0-Ae0tNZN2_%3DULuHWUy7XE6ESZcDDg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4Lw-yyemXQUkNN8EmQ2EWp%3DqekNMm_FzcLOoiW5uECMYg%40mail.gmail.com.

José Valim

unread,
Sep 14, 2018, 2:01:33 PM9/14/18
to elixir-l...@googlegroups.com
His implementation is correct. It is about categories, not tags. A certain entry can only belongs to a single category.
--

Sven Gehring

unread,
Sep 14, 2018, 2:50:14 PM9/14/18
to elixir-l...@googlegroups.com
> Point being, you wouldn't put a function for integers in the `String` module, so why would you put functions that convert data [...]
Well, Elixir doesn't. The only integer related functions in the String modules are conversion functions, which convert from/to Strings.
If I want to convert between strings and integers, I don't think looking at the `String` and `Integer` module docs is that confusing.

> Ok, then display them like you display the `since` data.
Personally, I feel like this would just clutter the documentation. If you really want to aggregate conversion functions for example,
I feel some kind of list in the getting started section might be more helpful, for newcomers to find them (like https://elixir-lang.org/getting-started/alias-require-and-import.html)
If you're already on the Elixir ExDoc page and in the (one of the two) specific modules you care about, you will find the functions without them being tagged.

--
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-co...@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.

Alexander Marks-Katz

unread,
Sep 14, 2018, 3:59:52 PM9/14/18
to elixir-l...@googlegroups.com

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.

--
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-co...@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.

Alexander Marks-Katz

unread,
Sep 14, 2018, 4:04:16 PM9/14/18
to elixir-l...@googlegroups.com
> I feel some kind of list in the getting started section might be more helpful, for newcomers to find them (like https://elixir-lang.org/getting-started/alias-require-and-import.html)

I think this is a good idea: to add a page after 8. Modules and functions that introduces categories of functions within the Elixir core.

English3000.org: A data-driven approach to language learning.

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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAFuVuxxSiXM8rXeGod%2B%2Bf6sFZQ0QJsvn%2BzSRSVMSpPaRiLMc7A%40mail.gmail.com.

english...@gmail.com

unread,
Sep 16, 2018, 6:11:15 PM9/16/18
to elixir-lang-core
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` works for any type by implementing the `String.Chars` protocol, which calls `Atom.to_string/1` if it receives an atom, `Integer.to_string/1` if it receives an integer, 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:

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....@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
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+unsubscribe@googlegroups.com.
Reply all
Reply to author
Forward
0 new messages