-
Bug
-
Resolution: Fixed
-
Low
Since 13th May 2020, these rules apply:
- @link will be used always to link to URLs (and not to elements).
- @see will be used always to link to FDQN element (and not to URLs).
- Both tags can be used standalone or inline, within a phpdoc comment.
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
- has a non-specific relationship to
-
CONTRIB-8095 Enforce coding guidelines for inline tags in phpdocs
-
- Closed
-