Elixir Notes: Mix Tasks and @shortdoc

I had not tried to write my own mix tasks until this week. The Mix.Task documentation made it look ridiculously easy:

In summary:

• create a file under lib/tasks
• use Mix.Task
• define a run/1 function – receives the command-line arguments (as a list of strings)

And… it worked. I felt awesome.

A Small Problem

My new task didn’t show up with the others in mix help. A quick search took me, ironically, 3-4 paragraphs below the above screenshot, on the same page 😅

Define the @shortdoc attribute if you wish to make the task publicly visible on mix help. Omit this attribute if you do not want your task to be listed via mix help.

Except … that didn’t work…

⚠️ note that mix help doesn’t recompile the code … try mix compile first, to ensure your changes show up.

Deep Dive

I couldn’t find a quick answer, so I cloned the Elixir code and started to grep.
(specifically: rg '[^@]shortdoc')

I found this:

As per line 178 (@ elixir 1.12), Mix.Task.shortdoc(module) is used to filter qualifying tasks. What did iex have to say about that?

Hmmm… it works?! 🤔

It took a lot more digging, but here’s the complete picture:

(click to enlarge)

• yes, @shortdoc comes into play to filter the list, at #3
• but, before that, the listed tasks are filtered by @moduledoc also…

Lessons Learned?

I found out about the behavior of @moduledoc before I found it in the code. That certainly directed my search. The reasons that I kept digging:

• as always, I found the Elixir code to be approachable 💖
• I couldn’t find WHY the @moduledoc had to be present – which seemed like a learning opportunity
• I couldn’t find documentation that explicitly explained this behavior – @moduledoc is said to provide the documentation printed by mix help taskname