Uploaded image for project: 'Moodle'
  1. Moodle
  2. MDL-72013

Add jsdoc validation checks

    XMLWordPrintable

Details

    • MOODLE_310_STABLE, MOODLE_311_STABLE, MOODLE_400_STABLE
    • MOODLE_310_STABLE, MOODLE_311_STABLE
    • MDL-72013-311
    • MDL-72013-master-int
    • Hide

      Date: Thu Oct 14 15:44:23 2021 +0800

      1. Run eslint

        grunt eslint:amd
        

        1. Confirm that no errors were reported
      2. Open lib/amd/src/toast.js in your editor
      3. Modify the top docblock (where @module is defined) to add:

        @package mod_assign
        

      4. Delete the @param line for addToastRegion
      5. Modify the add function's docblock to swap the order of message and configuration
      6. Save changes
      7. Run eslint

        grunt eslint:amd
        

        1. Confirm that failures were reported
      Show
      Date: Thu Oct 14 15:44:23 2021 +0800 Run eslint grunt eslint:amd Confirm that no errors were reported Open lib/amd/src/toast.js in your editor Modify the top docblock (where @module is defined) to add: @package mod_assign Delete the @param line for addToastRegion Modify the add function's docblock to swap the order of message and configuration Save changes Run eslint grunt eslint:amd Confirm that failures were reported

    Description

      This is a followup of MDL-71113, where generating core's JS documentation with jsdoc was added. Original comment and code proposed there was:

      I'm going to fail testing of this as I've just realised that we should have a Github Action check for any errors.

      It's a really easy check:

      npx jsdoc -c .grunt/jsdoc/jsdoc.conf.js --pedantic
      

      Proposed diff:

      index c85fd54b84e..2de0119a599 100644
      --- a/.github/workflows/push.yml
      +++ b/.github/workflows/push.yml
      @@ -38,6 +38,9 @@ jobs:
                 git reset -- npm-shrinkwrap.json
                 git diff --cached --exit-code
       
      +      - name: JSDoc Error failures
      +        run: npx jsdoc -c .grunt/jsdoc/jsdoc.conf.js --pedantic
      +
         PHPUnit:
           runs-on: ${{ matrix.os }}
           services:
      

      It was agreed to create this followup to allow the weekly cycle to continue and have some more time to see how and where this could be implemented.

      In this issue we should be able to decide, and implement:

      • What we want to be reported.
      • What should lead to a failure in the check.
      • Where we can add that new check (core's GHA/Travis, CiBoT, moodle-plugin-ci, grunt....)

      This issue goes further than the original proposal and adds use of the eslint-jsdoc plugin with configuration to meet minimum documentation correctness.

      With this patch the following changes will be observed:

      • missing, incorrectly ordered, incorrectly defined, or additional parameters and properties for functions, methods, etc. will raise an error
      • incorrect use of the @package tag will raise an error
      • incorrect use of the @access tag will raise an error
      • incorrect alignment of docblock asterisks will raise a warning

      Any error will lead to a failure in eslint, which will prevent the building of the AMD module.

      Attachments

        Issue Links

          Activity

            People

              dobedobedoh Andrew Lyons
              stronk7 Eloy Lafuente (stronk7)
              Tim Hunt Tim Hunt
              Eloy Lafuente (stronk7) Eloy Lafuente (stronk7)
              Eloy Lafuente (stronk7) Eloy Lafuente (stronk7)
              David Woloszyn, Huong Nguyen, Jake Dallimore, Michael Hawkins, Stevani Andolo
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                8/Nov/21

                Time Tracking

                  Estimated:
                  Original Estimate - Not Specified
                  Not Specified
                  Remaining:
                  Remaining Estimate - 0 minutes
                  0m
                  Logged:
                  Time Spent - 6 hours, 11 minutes
                  6h 11m