Re: [elixir-core:8296] [Proposal] Add tags to Elixir core functions

2018-09-16 Thread english3000 . org 
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:
>
> 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
>>
>> -- 
>> 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
>>  
>> 
>> .
>> 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

Re: [elixir-core:8294] Proposal: Comments in AST

2018-09-16 Thread José Valim 
This is really, really hard to do because it would overcomplicate the
language grammar, as it would have to take comments into account at every
step. I am not even sure if it is possible. If someone wants to try it out
though. :)

That's why most tools end-up handling comments on the side, separated from
parsing.

*José Valim*
www.plataformatec.com.br
Skype: jv.ptec
Founder and Director of R

On Sun, Sep 16, 2018 at 6:59 PM, Steve Morin  wrote:

> Wanted to see what peoples thoughts are about adding comments to the AST.
>
> One use-case is to be able to parse and manipulate Source files outside of
> just macros but in that case you would want to be able to preserve
> comments.
>
> E.g. Read a source file, manipulate it, write that source file back to a
> file.
>
> This would allow people/tooling to use elixir to parse and manipulate
> source files.
>
> If this might disturb existing consumers of the AST maybe this could be
> added as a option to existing Macro functions so that I could be turned on
> for people with this use-case.
>
> --
> 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/ms
> gid/elixir-lang-core/955237D8-31DE-448C-9777-1104F1175DC7%40gmail.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2B3rS%2BWrD8BbPHLMSS123A4NW29T%2BwM-V40V_1OgQbq_w%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: [elixir-core:8293] Proposal: Comments in AST

2018-09-16 Thread Louis Pilfold 
Hi Steve

The formatter extracts comments from Elixir source like so:
https://github.com/elixir-lang/elixir/blob/9cf118bd123deb945be71bf3ea2b48cd271088f0/lib/elixir/lib/code/formatter.ex#L199-L225

This may help you.

Cheers,
Louis

On Sun, 16 Sep 2018 at 17:59 Steve Morin  wrote:

> Wanted to see what peoples thoughts are about adding comments to the AST.
>
> One use-case is to be able to parse and manipulate Source files outside of
> just macros but in that case you would want to be able to preserve
> comments.
>
> E.g. Read a source file, manipulate it, write that source file back to a
> file.
>
> This would allow people/tooling to use elixir to parse and manipulate
> source files.
>
> If this might disturb existing consumers of the AST maybe this could be
> added as a option to existing Macro functions so that I could be turned on
> for people with this use-case.
>
> --
> 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/955237D8-31DE-448C-9777-1104F1175DC7%40gmail.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/elixir-lang-core/CABu8xFCqNwQWGjr7PmeGgNOsKBcbFfQHoKLXmZuHahSv_vTxtA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[elixir-core:8292] Proposal: Comments in AST

2018-09-16 Thread Steve Morin 
Wanted to see what peoples thoughts are about adding comments to the AST.  

One use-case is to be able to parse and manipulate Source files outside of just 
macros but in that case you would want to be able to preserve comments.  

E.g. Read a source file, manipulate it, write that source file back to a file.  

This would allow people/tooling to use elixir to parse and manipulate source 
files.

If this might disturb existing consumers of the AST maybe this could be added 
as a option to existing Macro functions so that I could be turned on for people 
with this use-case. 

-- 
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/955237D8-31DE-448C-9777-1104F1175DC7%40gmail.com.
For more options, visit https://groups.google.com/d/optout.