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

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

    XMLWordPrintable

Details

    • MOODLE_310_STABLE, MOODLE_311_STABLE, MOODLE_400_STABLE
    • MOODLE_310_STABLE, MOODLE_311_STABLE
    • MDL-71113-311
    • MDL-71113-master
    • 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).

    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

              dobedobedoh Andrew Lyons
              dobedobedoh Andrew Lyons
              Mathew May Mathew May
              Eloy Lafuente (stronk7) Eloy Lafuente (stronk7)
              Anna Carissa Sadia Anna Carissa Sadia
              Andrew Lyons, Huong Nguyen, Jun Pataleta, Michael Hawkins, Shamim Rezaie, Simey Lameze, Stevani Andolo
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                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