Feature request: Identifier references in comments and documentation

Ecosystem
1

Hello!

It would be nice to have special syntax for identifier references in comments. When renaming symbols, it’s somewhat annoying to go around correcting documentation or comments referencing renamed identifiers. This seems very automate-able…

Thanks!

2

Hello, you can request the feature here: GitHub · Where software is built

3

There is the syntax {!Foo.bar} that is supported by ocamldoc and odoc I believe, is it what you are looking for? (This does not by itself provide any automation.)

1 Like
4

The problem is that if Foo.bar is renamed to say Foo.bar2 (eg), the reference Foo.bar will become invalid. I think they are asking for a stable identifier to be able to use as a reference even across changes in identifier names in the source code. Although one might question whether that is a good idea in the first place.

5

That’s not exactly what I understood from the OP’s request. I take it more like OCaml’s refactorization tools should work in the doc strings too.

Note that if you use the syntax @gasche mentioned you will get a warning about an unknown identifier which is just one step short of what the OP wants.

1 Like
6

Ah, I didn’t know about that, thank you @gasche! Yes, this is not ideal but certainly better than nothing!