Improve mix.exs related documentation

[Eiji7]

Elixir and Erlang/OTP versions

N/A (latest documentation on hexdocs)

Operating system

N/A (latest documentation on hexdocs)

Current behavior

I had an interesting discussion on forum: https://elixirforum.com/t/etsselect-an-ets-match-spec-builder-from-a-simple-query-language/65513

As in linked topic I have proposed some things based on what I remembered from documentation. However after first reply I have started to look more deeply. While some unusual case deserve a separate article/blog post we found some things in documentation that could be improved …

---

First of all in Dependency definition options the :optional option explicitly says:

any other project that depends on the current project won’t be forced to use the optional dependency

We found that :only option have similar behaviour, but it's not documented while projects like :phoenix uses it as well. So it ended that a proposal for setting :optional to true for said deps was correct in terms of documentation, but since :only option was already used the discussion went into confusion until I have analysed :only option behaviour.

---

Second issue is a bit different … In a good documentation one of the most important thing is how easy is to navigate between pages. After all changes to sidebar, search and many other features I'm sure you are aware of it. Kindly please notice that navigating between pages with all mix.exs related documentation is not intuitive.

The documentation is divided into many pages including Mix.Project module documentation and mix tasks. It would be not a big problem if … some of those documentation pages would not be in the same project …

Expected behavior

I believe that :only option mentioned above needs a better documentation.

In my opinion

(…) useful when declaring dev- or test-only dependencies (…)

is not clear enough. While test-only makes perfectly sense, other environments like dev and prod are not. The only: :prod behaves differently than only: :dev which is not clearly described. The dev-only term is also commonly used for phoenix routes (like dev-only routes for email preview or live dashboard) and those uses code from dependencies.

Following :optional documentation I suggest something like:

(…) useful when declaring non-prod dependencies that would not be forced to use in other project that depends on the current project (…)

Not sure if there is a real world case for only: prod, optional: true, but if so then there should be a note that setting :optional option to true is required in such case.

---

I believe that there should be a single page (either Mix.Project module documentation) or a separate extra page which either lists and describes all options (less likely) or lists and describes the most important ones (like in Mix.Project) and links other functions/options supported in mix.exs like:
Package configuration | mix hex.build

This is important to have all information in one place without a need to search each function/option separately. For example in my case when I have released a very first package I was following Publishing a package article which does not links to a mix tasks and also it does not mentions exclude_patterns option while other options are mentioned. Also the task does not lists :organization option and ex_doc related configuration mentioned in article.

This is why when reading one source people may not have idea about all possible options. As you can see if some page lists said options it's not guaranteed to be complete list because "some other page" lists those options. It would be "ok" if we talk about 2, maybe 3 pages, but as you can see even if we read hex and mix projects documentation we may still miss some options. This is very confusing behaviour that I believe should be corrected "this or other way".

Thanks for your work and time.

[josevalim]

I will document the differences between only and optional. For the second one, I recommend submitting a pull request to the "Publishing a package" page in Hex, which links to the mix deps docs as well as the Library Guidelines. The reason a single page does not make sense is because Elixir docs apply to all kinds of dependencies, including the ones you add by Git. So the Hex.pm page is a good place to put everything to together, when it comes to Hex.