Need modules attributes in moduledoc :(

[adkron]

I use nimble options to build documentation, and mix help uses moduledoc as the output. I need to use the module attribute to create my documentation.

Elixir / OTP Version

Erlang/OTP 25 [erts-13.1.4] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit]

Elixir 1.14.3 (compiled with Erlang/OTP 25)

Example Input

defmodule Mix.Tasks.DenoEx.Install do
  use Mix.Task

  @shortdoc "Installs Deno"

  @options_schema [
    path: [
      type: :string,
      default: DenoEx.executable_location(),
      doc: "The path to install deno."
    ],
    chmod: [
      type: :string,
      default: "770",
      doc: "The permissions that will be set on the deno binary. In octal format."
    ]
  ]

  @moduledoc """
  A mix task that installs Deno into your project.

  # Usage

    > mix deno.install

  # Options

    #{NimbleOptions.docs(@options_schema)}
  """

  @impl true
  def run(args) do
    {:ok, options} =
      args
      |> OptionParser.parse(aliases: [p: :path], strict: [path: :string, chmod: :string])
      |> elem(0)
      |> NimbleOptions.validate(@options_schema)

    Mix.shell().info("Installing Deno to #{options[:path]} and setting permissions to #{options[:chmod]}")

    {chmod, _} = Integer.parse(options[:chmod], 8)
    DenoEx.DenoDownloader.install(options[:path], chmod)
  end
end

Current behaviour / Stacktrace

== Compilation error in file lib/tasks/install.ex ==
** (FunctionClauseError) no function clause matching in NimbleOptions.docs/2    
    
    The following arguments were given to NimbleOptions.docs/2:
    
        # 1
        nil
    
        # 2
        []
    
    Attempted function clauses (showing 2 out of 2):
    
        def docs(schema, options) when is_list(schema) and is_list(options)
        def docs(%NimbleOptions{schema: schema}, options) when is_list(options)
    
    (nimble_options 1.0.2) lib/nimble_options.ex:403: NimbleOptions.docs/2
    lib/tasks/install.ex:13: (module)

Expected Output

defmodule Mix.Tasks.DenoEx.Install do
  @shortdoc "Installs Deno"

  @options_schema [
    path: [
      type: :string,
      default: DenoEx.executable_location(),
      doc: "The path to install deno."
    ],
    chmod: [
      type: :string,
      default: "770",
      doc: "The permissions that will be set on the deno binary. In octal format."
    ]
  ]

  @moduledoc """
  A mix task that installs Deno into your project.

  # Usage

    > mix deno.install

  # Options

    #{NimbleOptions.docs(@options_schema)}
  """

  use Mix.Task

  @impl true
  def run(args) do
    {:ok, options} =
      args
      |> OptionParser.parse(aliases: [p: :path], strict: [path: :string, chmod: :string])
      |> elem(0)
      |> NimbleOptions.validate(@options_schema)

    Mix.shell().info("Installing Deno to #{options[:path]} and setting permissions to #{options[:chmod]}")

    {chmod, _} = Integer.parse(options[:chmod], 8)
    DenoEx.DenoDownloader.install(options[:path], chmod)
  end
end

[novaugust]

hey amos, thanks for the issue!

directive ordering breaking things is documented (albeit poorly) on the readme, but here's a fix for you that isnt documented there

you can move your options outside of the module into a naked variable and reference it in the module.

options_schema = [ ... ]

defmodule Mix.Tasks.DenoEx.Install do
  @moduledoc """
   ... #{NimbleOptions.docs(options_schema)}
  """
  
  ...

  @options_schema options_schema
end

Hope that helps.

Gonna leave this open for a bit to help others find it as well 🤙

[novaugust]

Updated the readme with more explicit first-run advice like this, fingers crossed people see it ;)

[adkron]

🤖 ❤️