Elixir: Discuss if @typedoc should be renamed to @doc

[josevalim]

There is a small inconsistency in that, besides @moduledoc, types are the only other construct that have a specific attribute for documentation, called @typedoc. For example, a @callback is documented with @doc and not @callbackdoc.

One could argue that callbacks are similar to functions and therefore are allowed to use the @doc attribute.

In any case, being allowed to use @doc everywhere, except for modules which would be ambiguous, may be more consistent. On the other hand, @typedoc can be considered more explicit, and it allow us to provide better error messages, for example, for unused attributes.

[yordis]

If the code do not suffer, at least as the person using the API I would push for use the same annotation.

And by so, allow me to use h/1 as well on typespec docs.

[devonestes]

Frankly, this has never crossed my mind as a problem. Once I saw a couple instances of @typedoc I learned pretty quickly that that's how we document types. If we get better error messages out of that, then I think it's totally worth it.

That said, I'd be fine with it either way.

[michalmuskala]

I wondered about exactly this some time ago. I think having @doc everywhere would be a better solution.

[OvermindDL1]

except for modules which would be ambiguous

It wouldn't be if the first @doc was for the module and the module doc was always required if there were any other doc's at all. ;-)

But yes, I'd prefer just @doc everywhere.

[whatyouhide]

I don't want to sidetrack the discussion, just a consideration: if we go with @doc for types (so a common interface with one module attribute for different constructs), I think we should consider renaming @describetag to @tag (and move it before the describe block). I don't want to discuss this here as it's off topic, just wanted to take it into consideration when discussing if we want to rename @typedoc.

[whatyouhide]

On second thought™, describe blocks are semantically a bit different for this particular case (they introduce a block so they're maybe closer to modules with @moduledoc) so scratch that, let's focus the discussion on @typedoc/@doc and maybe discuss @describetag/@tag somewhere else in the future.

[fertapric]

In any case, being allowed to use @doc everywhere, except for modules which would be ambiguous, may be more consistent. On the other hand, @typedoc can be considered more explicit, and it allow us to provide better error messages, for example, for unused attributes.

In order to have all the information, could you provide the error messages that will get worse after replacing @typedoc with @doc? I've tried with a @typedoc without a @type and I haven't seen any warnings (I also don't want to sidetrack the discussion, but should a warning be emitted on those cases?).

In addition, to give some weird examples for edge cases (that probably don't need to be covered):

@doc """
This is the doc for the function
"""
@type my_custom_type :: :foo | :bar | :baz
@spec my_fun(my_custom_type) :: :ok | :error
def my_fun(value) do
  # ...
end

[josevalim]

should a warning be emitted on those cases?

Yes, it should. :) But let's wait since it may be removed altogether.

In addition, to give some weird examples for edge cases (that probably don't need to be covered):

Good example of the downside. :+1:

[Eiji7]

I read it few times and got an idea, but I'm not sure yet about it. How about introduce something like @attrdoc? With this we will be able to document all module attributes which the developer deems necessary and this will also solve problem with differences between documenting @callback and @type. Of course placing @attrdoc right before @moduledoc, @doc, @attrdoc and @spec should emit warning.

[adkron]

I prefer the explicit @typedoc to @doc everywhere. Programmatically it leaves less corner cases that can be ambiguous as Fernando showed. I believe that it will be easier to process if we want to add/remove data that is different between the two types if we keep them explicit and separate.

Amos King
Binary Noggin

On Feb 20, 2018, at 17:53, Fernando Tapia Rico [e-mail] wrote:

In any case, being allowed to use @doc everywhere, except for modules which would be ambiguous, may be more consistent. On the other hand, @TypeDoc can be considered more explicit, and it allow us to provide better error messages, for example, for unused attributes.

In order to have all the information, could you provide the error messages that will get worse after replacing @typedoc with @doc? I've tried with a @typedoc without a @type and I haven't seen any warnings (I also don't want to sidetrack, but should a warning be emitted on those cases?).

In addition, to give some weird examples for edge cases (that probably don't need to be covered):

@doc """
This is the doc for the function
"""
@type my_custom_type :: :foo | :bar | :baz
@spec my_fun(my_custom_type) :: :ok | :error
def my_fun(value) do
# ...
end
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[josevalim]

@adkron @fertapric I guess the follow up question is: should we add @callbackdoc then? What would be the pros and cons of adding it?

[josevalim]

I will close this for now as there is no clear benefit of moving away from @typedoc. A reasonable guideline for now is, because both @spec and @callback are tied to function definitions, internally or externally, they use the @doc attribute.