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

Integrate jsdoc into Grunt and allow for JS Documentation to be generated

    XMLWordPrintable

    Details

    • Testing Instructions:
      Hide
      1. Update your Node dependencies

        npm ci
        

      2. Run the jsdoc tool:

        grunt jsdoc
        

        1. Confirm that there were no errors
      3. Open your site in your browser and navigate to the jsdocs (by appending /jsdoc to the site name) i.e. http://hostname/path/to/your/site/jsdoc
      4. Browse the documentation
        1. Confirm that most documentation is present

      Note: This issue does not seek to fix all documentation, but attempts to fix a great deal of it. More will come as we fix code.

      Additional testing step for jsdoc linting

      1. Run JSDoc manually:

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

        1. Confirm there was no error or output
      2. Edit lib/amd/src/str.js
      3. Add a new line just before the @copyright line:

        /**
         * Fetch and return language strings.
         *
         * @package   core
         * @module     core/str
         * @copyright  2015 Damyon Wiese <damyon@moodle.com>
         * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
         * @since      2.9
         */
        

      4. Run JSDoc manually:

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

        1. Confirm there was an error:

          WARNING: The @package tag does not permit a value; the value will be ignored. File: str.js, line: 16
          

      5. Check the exit code (must be the next command):

        echo $?
        

        1. Confirm that it was non-zero (i.e. it should be 1).
      Show
      Update your Node dependencies npm ci Run the jsdoc tool: grunt jsdoc Confirm that there were no errors Open your site in your browser and navigate to the jsdocs (by appending /jsdoc to the site name) i.e. http://hostname/path/to/your/site/jsdoc Browse the documentation Confirm that most documentation is present Note: This issue does not seek to fix all documentation, but attempts to fix a great deal of it. More will come as we fix code. Additional testing step for jsdoc linting Run JSDoc manually: npx jsdoc -c .grunt/jsdoc/jsdoc.conf.js --pedantic Confirm there was no error or output Edit lib/amd/src/str.js Add a new line just before the @copyright line: /** * Fetch and return language strings. * * @package core * @module core/str * @copyright 2015 Damyon Wiese <damyon@moodle.com> * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @since 2.9 */ Run JSDoc manually: npx jsdoc -c .grunt/jsdoc/jsdoc.conf.js --pedantic Confirm there was an error: WARNING: The @package tag does not permit a value; the value will be ignored. File: str.js, line: 16 Check the exit code (must be the next command): echo $? Confirm that it was non-zero (i.e. it should be 1).
    • Affected Branches:
      MOODLE_310_STABLE, MOODLE_311_STABLE, MOODLE_400_STABLE
    • Fixed Branches:
      MOODLE_310_STABLE, MOODLE_311_STABLE
    • Pull 3.10 Branch:
      MDL-71113-310
    • Pull 3.11 Branch:
      MDL-71113-311
    • Pull Master Branch:
      MDL-71113-master

      Description

      This issue is a placeholder to integrate jsdoc with Moodle to allow us to generate JS documentation easily for all AMD-based JS.

      This could also (possibly) document YUI and older-style module.js files, but those are low on the priorities.

      This is now significantly easier now that we have GruntfileComponents.js and components.json.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              dobedobedoh Andrew Lyons
              Reporter:
              dobedobedoh Andrew Lyons
              Peer reviewer:
              Mathew May Mathew May
              Integrator:
              Eloy Lafuente (stronk7) Eloy Lafuente (stronk7)
              Tester:
              Anna Carissa Sadia Anna Carissa Sadia
              Participants:
              Component watchers:
              Andrew Lyons, Dongsheng Cai, Huong Nguyen, Jun Pataleta, Michael Hawkins, Shamim Rezaie, Simey Lameze
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:
                Fix Release Date:
                12/Jul/21

                  Time Tracking

                  Estimated:
                  Original Estimate - Not Specified
                  Not Specified
                  Remaining:
                  Remaining Estimate - 0 minutes
                  0m
                  Logged:
                  Time Spent - 4 days, 1 hour, 46 minutes
                  4d 1h 46m