Elixir Notes: Mix Tasks and @shortdoc

July 4, 2021

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

Mix.Task documentation screenshot

In summary:

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:

code that checks for @shortdoc

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?

check in iex

Hmmm… it works?! 🤔

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

complete code picture (click to enlarge)

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:

Discuss on Twitter