Writing docs for macro methods

Questions / Help
1

I have this macro for which I am writing @doc and @moduledoc. The @moduledoc works fine, but @doc doesn’t show anything inside the macro. Is there any way I can write docs for the macro methods?

defmodule Paginator do
@moduledoc """
   paginator
"""  
defmacro __using__(options) do
  quote location: :keep do
    import Ecto.Query

    @options unquote(options)

   @doc """
      Apply limit and offset to the query if not provided and return meta.  
   """
     def paginate(query, params) do
     end
   end
  end
end
2

@leaf the Paginator does not actually contain the function paginate. A module that did use Paginator would have that function, but the Paginator module does not, so there’s nothing to document.

2 Likes
3

The pattern used by Ecto in such libraries is to define documented callbacks, so you would do something like:

defmodule Paginator do
  @moduledoc """
  paginator
  """  
  defmacro __using__(options) do
    quote location: :keep do
      import Ecto.Query

      @behaviour unquote(__MODULE__)

      @options unquote(options)

      def paginate(query, params) do
      end
    end
  end

  @doc """
  Apply limit and offset to the query if not provided and return meta.
  """
  @callback paginate(query :: Ecto.Queryable.t(), params :: keyword()) :: Ecto.Queryable.t() 
end
4 Likes
4

Thanks. That makes sense.

5

thanks its a good solution.