Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-6105

PHPDocs: Clarify/modify @link and @see phpdoc allowed usage

    XMLWordPrintable

Details

    • Bug
    • Status: Closed
    • Low
    • Resolution: Fixed
    • Coding style

    Description

      Policy: phpdoc @link and @see tags usage

      Since 13th May 2020, these rules apply:

      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.

      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

      Attachments

        Issue Links

          Activity

            People

              stronk7 Eloy Lafuente (stronk7)
              stronk7 Eloy Lafuente (stronk7)
              Marina Glancy, Eloy Lafuente (stronk7)
              Votes:
              0 Vote for this issue
              Watchers:
              9 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: