Hex url format: what can I assume?

Questions / Help
1

I’m working on a tool to visualize Elixir projects. I’d like to have hyperlinks to the source from each function call to its definition, including links to hex.pm for external packages. Can I assume that the url of a function documented on Hex using ExDoc will be: https://hexdocs.pm/#{app}/#{module}.html##{function}/{arity}?

I know that if the package author generates the docs with another tool, then I can’t assume anything, of course, but for now I won’t worry about that case.

2

Not application but package name is the first part in the url, also you can have an optional version between package name and module:

https://hexdocs.pm/elixir/1.5.0/Kernel.html

Also you can assume that callback functions in a behaviour module are prefixed with c:, eg:

https://hexdocs.pm/elixir/1.5.0/Access.html#c:fetch/2

While types are prefixed t::

https://hexdocs.pm/elixir/1.5.0/Access.html#t:access_fun/2

Some older versions of ex_doc did separate macros from functions, but I’m not sure anymore if there was a prefix…

3

And this is only for projects that use ex_doc, all others then all bets are off.

4

Yes, I know. I consider this to be a strength of the Elixir ecosystem, and that’s why I have discouraged in the past the use of any documentation tool that didn’t follow these conventions… Despite ExDoc’s deficiencies, I like the fact that the links to the functions and modules are predictable. Python’s solution to documenting projects and libraries, Sphinx, has a number of advantages over ExDoc, an is probably technically superior, as well as easier to customize. On the other hand, to generate links to the documentation you need to hunt for objects.inv under the projects’ directories, and specify the URL of the docs for each dependency, which is inconvenient. The fact that Elixir API docs are concentrated under hexdoc.pm is a very good thing.

I think that any ExDoc alternative should make it very easy to map from functions to links, and if possible, use the same convention as ExDoc.

1 Like
5

Yes, and the OP stated in his very first post, that he is aware of that fact.

But to be honest, which other tools are there besides ex_doc?

The only one I am aware of is :exygen, which I started some while ago as an experiment. It was meant to turn JavaDoc style annotations into a normalized markdown and then put it back into @doc so that :ex_doc can then process it.

But it is not only in a very early stage, its actually broken for every version of elixir and if it does something at all, it just puts the docs back as they are. Its still something that I want to finish, perhaps I’ll find some time during october to continue/restart it?

6

There is also the document generator for erlang, which I’ve seen some Hex projects use.

7

He said he writes an analyzer for elixir projects, not erlang.

8

Yep, but a lot of Elixir projects use Erlang code as dependencies, like look at cowboy is being used by every plug and phoenix project. ^.^