Warn when using links to fragment instead of dedicated reference

[MisterDA]

The Lwt documentation has snippets such as:

- {{: #3_Quickstart} Quick start} links these concepts to actual functions
  in Lwt – the most fundamental ones.
  
  ....
  
  {3 Quick start}

or

{{: #VALfoobar}

Sone of the references were correct at some point, but not anymore. Maybe odoc could warn against this pattern and suggest the appropriate {!…} pattern? In the first case, it would require adding a section and using {!section-…}, in the second {!val:foobar}.

It could also warn linking to a section that has no :section defined, if it doesn't do that already.

[Julow]

There's automatically a label for a heading, {!"quick-start"}. The syntax is weird because of the -, which needs to be escaped with quotes.

The {: ...} syntax is for arbitrary urls, I'm not sure it would make sense to interpret it for the purpose of raising warnings.

These anchors wouldn't work with Odoc 1.5.0 either, perhaps Lwt was using ocamldoc ? In this case, the migration might be more involved. There some doc about that here: https://github.com/ocaml/odoc/blob/master/doc/ocamldoc_differences.mld

[dbuenzli]

Is there anything actionable in this issue ? If not please close.

[Julow]

I see many of these in Opam packages (not just in Lwt) and it's always in the form {{: #VALfoobar}, never {{: index.html#VALfoobar}. I now think we should trigger a warning in this case and suggest the new syntax (when prefix is #VAL and #<digit>). Many of these exist and it's one of the breaking changes between ocamldoc and odoc.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.