Improve documentation for Mix.env

[michalmuskala]

No description provided.

[whatyouhide]

The usual wording is something like

This function should not be used at runtime (see env/0 for more information).

[whatyouhide]

I think this is too much information because most of it is duplicated (from import_config/1 for example). I would say something like:

This function should not be used at runtime. Mix is a build tool and may not be available after the code is compiled (for example in a release).

To differentiate runtime behaviour depending on the environment, it's recommended to use application environment (see Application.get_env/3). Proper configuration can be set in Mix.Config files, often per-environment (see Mix.Config.import_config/1 for more information).

Wdyt?

[ericmj]

I think we should rethink our use of "runtime" because it is perfectly fine to use Mix.env in tasks. When do tasks run if not at "runtime"?

[michalmuskala]

What about something like this?

This function should not be used at runtime in application code (as opposed to infrastructure and build code like mix tasks)

[whatyouhide]

This function should not be used at runtime in application code (as opposed to infrastructure and build code like mix tasks)

Sounds good to me (Mix capitalized and trailing period assumed 😄).

[michalmuskala]

Updated

[whatyouhide]

Thanks @michalmuskala! 💟