josevalim
Call to library authors: define "Nutrition facts" for your meta-programming
One common concern about using Elixir libraries is that use SomeModule does not make clear how it impacts the caller. While the goal of use is precisely to provide a common extension point, and most of the time those changes are minor, it is impossible to know what it does without reading the source code.
For this reason, from Elixir v1.15, we are recommending libraries to include a summary alongside each module, typically within the first section of its @moduledoc, that succinctly explains the impact of using said modules. In this pull request, we have added this note to all use XYZ modules in stdlib, like this:
> #### `use GenServer` {: .info}
>
> When you `use GenServer`, the GenServer module will
> set `@behaviour GenServer` and define a `child_spec/1`
> function, so your module can be used as a child
> in a supervision tree.
Which will be rendered like this (see block at the bottom):
Think of it as “Nutrition facts” for meta-programming. If you are a library author and your modules can be used, please consider doing the same. 
Trending in Notices
Other Trending Topics
Latest on Elixir Forum
Sponsor Spotlight
Producing high quality Elixir screencasts since 2017.
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #deployment
- #library
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #channels
- #elixirconf
- #exunit
- #discussion
- #code-sync
- #javascript
- #podcasts
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixir-ls
- #phoenix_html
- #iex
- #blog-post
- #graphql
- #genstage
- #ai
- #elixirconf-us
- #websockets
- #supervisor
- #advent-of-code
- #distillery
- #processes
- #api
- #forms
- #metaprogramming
- #hex
- #performance
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Error tracking, logs, uptime, and Just Enough APM. Built for developers.
Practical resources that improve the lives of professional developers.
Producing high quality Elixir screencasts since 2017.
The deployment platform built for Elixir: PaaS ease, VPS control.
The team behind Membrane, Popcorn, LiveDebugger. Available for hire.
Courses that'll move you from confusion to "Aha, now I get it!"
First 10 of 21 Posts
josevalim
kip
Good idea. I’ll update the ex_cldr libs over the next week or so.
Update: added to the ex_cldr README and the Cldr module and published to
hex.pm.Nicd
This is where libraries that don’t use
usewin, nothing to document!sergio
Best code is no code!
sodapopcan
With careful consideration,
usebeneficially cleans up a lot of noise and I’m glad it exists.(•_•) even if it is a bit
( ••)>⌐■-■
(⌐■■) over
usedSorry, I couldn’t resist. I’ll see myself out.
aiwaiwa
In this case, it feels like Kernel — Elixir v1.20.2 itself could say a bit less obscure about the
useitself.Right now it says
Uses the given module in the current context.as a first sentence. It gives more room for questions like “what is context?”. “what doesusesmean?” instead of hinting that there will be something that gets generated along with importing.In fact hovering over
usein VSCode is what I do when trying to get a refresher on what it actually performs.christhekeele
I think it’d be helpful for IDEs to replace the hinttext for such things to display the@docof the__using__macro for the module itself, rather than the general docs foruseand theModulerespectively. If the library has nutrition facts set up, that’d make it a really clean development experience!Oh never mind, I see that the nutrition facts in stdlib are in the
@moduledocnot the macro@doc, so the current experience is ok.aiwaiwa
Right, but hovering over
:controllerin Phoenixuse ProjectWeb, :controllercould’ve unwrapped what’s a bunch of stuff is delivered to you by it.
useshows macro’s hint.ProjectWebprovides nutrition facts.:controllergives a clue of what is being brought in.fceruti
On a somewhat related note, a cool feature available on neovim using elixir-tools, is the expand macro:
aiwaiwa
Thank you! It’s a great feature! The hint is you need to select for it to actually work, I thought it was broken!
And it duplicates the output on my end too in VSCode.