Right now the coding style, about the @link and @see tags is as follows:

Ref.: https://docs.moodle.org/dev/Coding_style#.40see

• @see: only standalone, to reference other FDQN elements (classes, methods...)
• @link: standalone to reference URLs
• {@link}: inline, to reference both FDQN elements and URLs.

This comes from the night of the times, where phpdoc(umentor) (the product) itself was only allowing inline @link tags and not inline @see.

In fact there is a built'in check into local_moodlecheck that ensures that the only inline tag allowed is @link.

It always has been an "unbalanced" rule, but it was the only way.

But time changes and current status is:

1) phpdocumentor now supports both inline tags (apart from others that aren't being discussed here).

2) there are (both drafts right now) PSR-5 and PSR-19 about phpdocs, specifically the later considers to change them in the same way phpdocumentor does.

3) tools out there do "understand" @see pretty well, providing autocompletion (IDEs), generating links (documenting tools)...

So this is a proposal to change the use of those 2 tags, in a more logical way. Here it is:

1) @link will be used always to link to URLs (and not to elements).
2) @see will be used always to link to FDQN element (and not to URLs).
3) Both tags can be used standalone or inline, within a phpdoc comment.

Associated actions include:

a) Modify local_moodlecheck in order to provide basic support to the 1-2-3 proposal above.
b) Document the change
c) Explicitly, it's NOT required to change all current old-style ocurrences in code base. We'll follow a progressive approach here (new code and modified code).

And that's all. Options are:

A) We accept the change (1-2-3).
B) We continue as we are.

Ciao