Executando código na documentação de projetos Elixir

Algo que passou um pouco despercebido por mim no meus primeiros meses de Elixir, é que documentação (@moduledoc, @doc) são simplesmente module attributes, isso é, código que é executado durante a compilação como qualquer outra anotação com @, que você pode usar para guardar constantes, mapas, dados vindos de environments, etc.

Nosso @moduledoc e @doc são simplesmente strings, e podemos tratar essas strings como qualquer outra: com interpolação, concatenação, replacements, etc... ou até mesmo gerar elas dinamicamente.

Alguns exemplos na prática:

• Esbuild
  • Utiliza interpolação na doc para não precisar ter hardcoded na doc a última versão do Esbuild.
• Finch
  • Lê o arquivo README.md do repositório e faz uso dele como @moduledoc da lib.
  • Faz uso de interpolação para incluir na doc valores default usados em código.

O legal é que mesmo que você não gere documentação para seu projeto, você ainda vai poder desfrutar das suas docs dinâmicas através de ferramentas como o ElixirLS para trazer informações ricas sobre seus módulos e funções diretamente no seu editor.