@contract between @doc and def inhibits ExDoc, ExUnit.DocTest

[garthk]

a_contract_between_doc_and_def/0 below won't get tested or documented, without any warning to that effect:

defmodule NormContractVsDoctest do
  @moduledoc """
  Demonstrates interaction between `@contract` and `@doc`
  """

  use Norm

  @doc """
  Return `:a`.

      iex> a_bare()
      :a
  """
  def a_bare, do: :a

  @doc """
  Return `:a`.

      iex> a_contract_between_doc_and_def()
      :a
  """
  @contract a_contract_between_doc_and_def() :: :a
  def a_contract_between_doc_and_def, do: :a

  @contract a_contract_before_doc() :: :a
  @doc """
  Return `:a`.

      iex> a_contract_before_doc()
      :a
  """
  def a_contract_before_doc, do: :a
end

Strikes me the suppression might not be fixable without help from both, but you might well be in a position to see the @doc above @contract and give warning. Failing that, let me know and I'll raise a PR to document the problem so people don't have to find it in the issues.

[keathley]

Hmm...I've been wondering if we should look at using the @on_definition hook for contracts. I think that would solve both of these problems. We'd be able to check to see if we have a contract attribute (or attributes) set, and we'd still be able to include all of the relevant docs and whatnot. Its probably more work to do it that way but it might result in less surprises for the user. @wojtekmach would probably no more than me since he's spent more time with that code.

[wojtekmach]

on_definition is definitely interesting. I believe it’s used to annotate but not _change_ each definition, but it still might be useful. So the current approach is for each function to essentially define 2 functions, the inner one (the actual one) and the outer one that ensures the contract and calls super to invoke the inner one. I guess yet another approach is to not introduce separate function but rewrite the _body_ of the function to ensure the contract. That might compose better with other features of the language after all.

…

On 24 May 2020, at 17:03, Chris Keathley ***@***.***> wrote: Hmm...I've been wondering if we should look at using the @on_definition hook for contracts. I think that would solve both of these problems. We'd be able to check to see if we have a contract attribute (or attributes) set, and we'd still be able to include all of the relevant docs and whatnot. Its probably more work to do it that way but it might result in less surprises for the user. @wojtekmach <https://github.com/wojtekmach> would probably no more than me since he's spent more time with that code. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#80 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAASSJ2BAEPIKRFLQAWWCRDRTEZMHANCNFSM4NFUD46Q>.

[Qqwy]

There are two problems with using on_definition:

1. on_definition is called once per function clause rather than per function as a whole.
2. The result of the callback that on_definition calls is not used in any way. As such it cannot be used to e.g. insert code into a function (clause), at least not directly.

An alternative might be to override def/ defp directly instead, which has the disadvantage of making it (near?-)impossible to use Norm in combination with another library that overrides these in the same module.
Another alternative is overriding defmodule, which has the unfortunate (backwards-incompatible) consequence that Norm needs to be referenced outside of the modules in which it will be used. The advantage of this alternative is however that all complexity related to overriding @ and depending on defoverridable can be removed.