Phoenix: Documentation for static_path/2 is unreachable

[britto]

Expected behavior

In our Phoenix apps we normally call static_path/2 from our views, passing a conn and a path. Documentation for that function should be available in hexdocs.

Actual behavior

Helpers generated in Phoenix.Router.Helpers are not exposed in the docs. When we look for static_path there, the only result that shows up is for Endpoint.static_path/1, which may induce some confusion to newcomers.

Possible solutions

Since those helpers are generated dynamically, there's not much we can do to expose that sort of _public API_ to users. Adding some clarification to the docs of the static_path/1 callback is an option. Adding some info on the guides pages might be worth too.

[chrismccord]

We generate the documentation on the injected functions into your endpoint module:

https://github.com/phoenixframework/phoenix/blob/master/lib/phoenix/endpoint.ex#L677-L680

So the docs are available under hexdocs on your endpoint module. Closing since this is not an actual issue, but if you feel like this aspect could be made clearer in the docs somewhere or guides, please send a PR :)

[josevalim]

The issue is in static_path/2 that is generated by Phoenix.Router.Helper and that function is not documented anywhere. :)

[chrismccord]

@josevalim I'm confused since the Router.Helpers module indeed should show up in ExDoc, ie https://github.com/phoenixframework/phoenix/issues/2580

And we doc this function that is injected, so the docs should be there, no?

[josevalim]

That's a good point although a bit inconsistent, no? We need to look it up in the project documentation and not on the Phoenix one. Ideally we would also find it by searching for it on Phoenix docs.

[chrismccord]

@josevalim since 1.4 calls will be Routes.static_path, perhaps his problem will be resolved since folks will know where to look up the docs from their own project's ex_doc?

[josevalim]

It definitely helps, yes, because know I don't need to assort if it comes from the framework or my own codebase. Good call.