[FEATURES] Add @ module parsing

[OvermindDL1]

Add @ annotations (like doc and moduledoc and so forth, but stay generic).

[jjl]

+1. Without this, I'd feel a bit shit about releasing my modules on hex.

[OvermindDL1]

Actually docs are supported for a while now (and it adds a default undefined doc if not specified), I'm just wanting to support things like moduledoc as well, which shouldn't be too hard, should do that soon..., but documentation is already available on the functions themselves at least. :-)

[OvermindDL1]

@moduledoc is supported now as well, anything else needed?

[jjl]

Nothing else I've noticed :)

[jjl]

None of the type system related ones seem to work either

[OvermindDL1]

@type and @spec and so forth? Adding support for @type is pretty trivial, but @spec is quite difficult as I'd have to join every single protocol implementation's specs all together, meaning you could only specify it in the implementations anyway and not the protocol itself as the protocol definition may not know every implementation that may eventually be added... Is that what you are wanting?

[jjl]

Yes, @type and @spec and so forth. Tbh I don't even mind if it hides them from dialyzer for checking purposes, I just want ex_doc to see them.

[jjl]

That is to say I appreciate the problem with making it all work correctly with dialyzer. That would be nice in the long run, but for now I'd settle for having them visible in my docs :)

[OvermindDL1]

I don't think it's possible to have ex_doc see it and for dialyzer not to see it as I think ex_doc pulls it from the dialyzer type chunk. ^.^;

But yeah, I can add the ability to add type/typep/opaque in the protocol and type/typep/opaque/spec/specp in the implementations. I don't have time right at the moment (PR's welcome ^.^) but keep pinging me on occasion (IRC is fine :-) ) so when I do get time I will get that done. :-)

[OvermindDL1]

I should probably also add a @moduledoc false in implementations by default too unless the user overrides it, hmm...

(Typed this here for future reminding...)

[jjl]

Ah, I think I wasn't clear.

In the protocol itself, I would like to document the expected types of the function so that an implementer may easily understand it. So really the change would just be to copy the type/typep/opaque/spec inside the defprotocol_ex when generating the protocol module, which is less of a task than what you're suggesting :)

My time is also quite limited at the moment. This is a 'nice to have' for me, not a blocker so it's likely to be a little while before I can commit time to it also. I'll link an issue about types there to this issue

[OvermindDL1]

Allowing spec's inside the Protocol definition seems difficult though? How would you allow for all possible types that the implementations could accept without some kind of implementation type mapping or just using any()?

[jjl]

I think you're letting perfect be the enemy of workable :)

Let me give you an example:

defprotocol_ex Foo do
  @spec frob(term()) :: {:ok, term()} | {:error, term()}
  def frob(foo)
end

Our simple frob method doesn't do much, but it does have a contract for return values. It would be nice to have this in the documentation ex_doc generates.

I personally don't mind too much that dialyzer might generate warnings saying that the types don't match up in the generated module, so long as I can have the types in my documentation.

[OvermindDL1]

Heh, term() is any() though, so it would allow dialyzer to accept things to be passed in that would actually crash though?

I just need to get some time to do it right, it's not hard, just a touch involved... ^.^