Should not the links point to the latest version in the documentation?

Phoenix Forum Proposals/Suggestions
,
1

I am reading (Once more) the Phoenix web framework documentation, in the From endpoint to views section contained in the Request life-cycle topic; The URL to the Plug documentation (The link is located in the second paragraph. [Plug] is a library and a specification…) right now is pointing to v1.16.1, should not the URL be updated to point to v1.18.1 instead?

I did not find (Doing a rather quick search) the repository to the documentation so I can propose a pull request.

Thanks.

2

Good catch!

In any page you can click a link </> on the top right corner of each section and it will send you to the repository with the respective code, in this case phoenix/guides/request_lifecycle.md at v1.8.1 · phoenixframework/phoenix · GitHub

Notice there’s a link to the “Plug guide” which points to the latest version (no version in the URL).

I think a good change would be to update the “Plug” link to remove 1.6.1/ from the URL.

3

Thank you for your answer, I would have never guess </> contains the link to the GitHub repository, jehehe. Why not the octocat? </> looks good anyway.

Now, I am not sure if the documentation gets some sort of post-processing prior of being published, because Plug is not even marked down as a link, you know, [text](URL), it is a plain word between backticks in the related mark down code for the aforementioned page.

There you have it, happy weekend!

4

ex_doc is the doc generator for Elixir. it will do its best to form links for modules, functions, types and callbacks from the text within backticks. Thats how the docs are generated and how iex is able to introspect documentation too.

1 Like
5

The source code could be hosted anywhere not just on github.

6

The <> or </> symbol is often associated with “code”. The links are not necessarily to GitHub, it depends on the project configuration.

The documentation is written in Markdown format alongside the implementation of modules and functions.

The ex_doc library is the tool to extract the documentation and produce that nice website (and an ebook too!), and then it can publish the content to hexdocs.pm, a central repository of documentation.

You can also generate documentation for your own projects, even if you never intend to publish it online.

Now, why is it linking to version 1.16.1? I just checked, that is the version locked in phoenix/mix.lock at v1.8.1 · phoenixframework/phoenix · GitHub.

So I think ExDoc is interpreting Plug as a module and conservatively generating a link to the docs at the version the project has been tested with. I don’t know if that behavior is configurable.

1 Like