Very poor doc experience in iex

[myronmarston]

I'm used to poking around in iex using h to figure out library APIs. Your hexdocs.pm docs are pretty good but in iex the docs are awful:

I'm able to look at the source and hexdocs.pm to figure things out, but it would be great if you had usable docs available in iex. Actually, the reason I was even trying erlcloud was because I first tried ExAws, noticed the lack of iex docs and took that as a sign that ExAws is just a prototype so far, and that I should therefore look elsewhere for an S3 client. I guess I'm spoiled by many other elixir libraries having good docs available in iex :).

[benwilson512]

Let me offer an analogy. Presumably you're familiar with Ecto. Definitely not prototype software.

You misunderstand what ExAws.S3 is. It operates in a manner very similar to an Ecto Repo, in that it simply implements the callbacks defined in a behaviour module, in this case ExAws.S3.Client. The documentation and typespecs are associated with the callbacks, they are not and to my knowledge cannot be injected into every module that implements that behaviour via use ExAws.S3.Client.

I do see your point though, in that it would be nice to be able to point people to a good module for documentation in iex. If you do h ExAws.S3.Client you get the moduledoc but not the callback docs. Perhaps there's a way to access that via h/1.

[benwilson512]

From what I've gathered on IRC it is not possible at this time to get the docs for individual callbacks from h/1 in iex. This is definitely unfortunate, and you should consider making an issue for it there. However, this isn't anything to do with ExAws. I will add a note to the moduledoc of the S3, Dynamo and so on modules to make it clear that you should look at the docs in the .Client modules.

[myronmarston]

Presumably you're familiar with Ecto.

Barely. I'm very new to Elixir and have played with Ecto for a day or so but that's it. I don't remember having any particular problem getting docs for ecto in iex. For the specific example you showed, it at least names the arguments to the ecto function. For ExAws, the arguments are named in iex as arg0, arg1, etc, which gives no suggestion about their purpose. Is it possible to at least get the arguments named in the minimal bit displayed in iex?

Anyhow, being new to elixir, I confess I don't understand what the issue with behavior modules and callbacks is that prevents the docs from being usable in iex. Seeing the method signature with arg0, arg1, etc made me initially think that ExAws was just a prototype (or in some alpha status) and not something I should bother with trying yet. If it's going to remain like that (and it sounds like it is, due to elixir restrictions), I'd recommend adding a note to your README to mention that this is a known, unsolvable issue due to elixir restrictions and that folks should consult the hexdocs.pm docs instead. That'll help keep new users like me from getting frustrated and thinking this is just a prototype.

Thanks!