search

elixir-lang / ex_doc

ExDoc produces HTML and EPUB documentation for Elixir projects
http://elixir-lang.org
Other
1.45k stars 324 forks source link

Do not link to undocumented types #110

Closed ericmj closed 9 years ago

ericmj commented 10 years ago

Here: http://elixir-lang.org/docs/master/Version.html we link to the types Version.Schema.t and Version.Requirement.t. The types are not documented which is creating 404 links.

We should make sure we are not creating 404 links and we could warn that we are referencing a type that is not documented.

pminten commented 10 years ago

It looks like this is a problem with the autolinker, while it does check whether modules and functions exist in the current project it doesn't do so for types.

jwarwick commented 10 years ago

I spent a little bit of time looking at this and here's what I found. Suspect you guys already knew most of it, but I'm going to say it out loud for my understanding.

For the Version.Schema.t example, Version.Schema is a defrecord inside Version which does not have any documentation. ExDoc.Retriever.verify_module/2 removes these records from the list of modules to build documentation pages for. There is a comment calling out this fact in the code. Something about waiting for maps...

When ExDoc.HTMLFormatter.Autolink.typespec/3 runs, it calls ExDoc.HTMLFormatter.Autolink.get_source/2 which doesn't find Version.Schema in the local aliases list, but does find the beam file in the elixir lib path. At that point it constructs a link to where the doc page would be (had it not been stripped by the Retriever). You need this elixir lib path check in general to catch other generic types (like String).

Based on this, I don't see an easy way to catch this case. One option would be to allow doc pages to be created for these records. Or find some way to check __info__ and figure out it's not something we should be linking to.

josevalim commented 9 years ago

Closing in favor of #192.