Update files headers and documentation

index.js

@@ -1,3 +1,14 @@
+/**
+ * @file index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @brief Entry point to the command line tool
+ *
+ * It parses the arguments passed to the command line tool and decides which module to invoke
+ */
+
 const minimist = require('minimist')
 const shell = require('shelljs')
 

src/bump/index.js

@@ -1,3 +1,15 @@
+/**
+ * @file src/bump/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @brief Entry point for bump command
+ *
+ * This command (pkp-plugin bump) runs on a plugins root folder (containing version.xml).
+ * It provides an interactive CLI to collect the new version and release date of the plugin,
+ * then updates the XML file.
+ */
 const xml2js = require('xml2js')
 const inquirer = require('inquirer')
 const chalk = require('chalk')

src/help.js

@@ -1,3 +1,12 @@
+/**
+ * @file src/help.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ *
+ * @brief Prints the help of the command line (when running pkp-plugin help)
+ */
 const chalk = require('chalk')
 const { log, warn, info } = require('./utils/log')
 

src/release/index.js

@@ -1,3 +1,13 @@
+/**
+ * @file src/release/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @brief Entry point for release command
+ *
+ * This command (pkp-plugin release) is to be implemented
+ */
 const { warn } = require('../utils/log')
 
 module.exports = () => {

src/utils/checkSumFile.js

@@ -1,8 +1,18 @@
-const crypto = require('crypto')
-const fs = require('fs')
 /**
- * Calculates the md5 check sum of a file
+ * @file src/utils/checkSumFile.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ *
+ * @brief Helper function to calculate the md5 check sum of a file
+ *
+ * This calculates checksum of a file (defaulting to MD5) and provides an easier
+ * promise-based interface to creating a hash with crypto package
  */
+const crypto = require('crypto')
+const fs = require('fs')
+
 module.exports = function checksumFile (path, hashName = 'md5') {
   return new Promise((resolve, reject) => {
     const hash = crypto.createHash(hashName)

src/utils/downloadPackage.js

@@ -1,9 +1,19 @@
+/**
+ * @file src/utils/downloadPackage.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ *
+ * @brief Helper function to download a file
+ *
+ * Downloads a file from the internet taking into consideration follwing a redirect
+ * which is needed for Github links
+ *
+ */
 const https = require('follow-redirects').https
 const fs = require('fs')
 
-/**
- * Downloads a file from the internet following the redirect (which is needed for Github links)
- */
 module.exports = (package, fileName) => {
   return new Promise((resolve, reject) => {
     const file = fs.createWriteStream(fileName)

src/utils/files.js

@@ -1,3 +1,13 @@
+/**
+ * @file src/utils/files.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @module files
+ *
+ * @brief Helpers to promisify and simplify reading and writing files
+ */
 const fs = require('fs')
 
 const readFile = (fileName, encoding = 'utf8') => {

src/utils/log.js

@@ -1,3 +1,16 @@
+/**
+ * @file src/utils/log.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @module log
+ *
+ * @brief Wrapper around logging functions
+ *
+ * Provides a wrapper around console.log, info, error to consolidate the use of colors
+ * for different log actions (coloring using chalk library)
+ */
 const chalk = require('chalk')
 
 const info = (...args) => {

src/utils/plugins/extractAllReleasesFromXml.js

@@ -1,17 +1,26 @@
-const xml2js = require('xml2js')
-
-const { readFile } = require('../files')
-const { info } = require('../log')
-
-const parser = new xml2js.Parser()
-
 /**
+ * @file src/utils/plugins/extractAllReleasesFromXml.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ *
+ * @brief Helper function to extract all releases from a Plugin Gallery xml file
+ *
  * The function loops through the plugins and their releases and creates a text file containing a list
  * of the releases and their MD5 sums This is then consument by the bash script "checkMD5sum" that
  * downloads all the releases and compares their MD5 sums with the content of the generated file
  *
  * @param {string} filePath the path to the file to parse and extract the releases info from
+ *
  */
+const xml2js = require('xml2js')
+
+const { readFile } = require('../files')
+const { info } = require('../log')
+
+const parser = new xml2js.Parser()
+
 const extractData = async filePath => {
   info(`Extracting releases from ${filePath}`)
 

src/validate-all-releases/index.js

@@ -1,11 +1,21 @@
+/**
+ * @file src/validate-all-releases/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @brief Entry point for validate-all-releases command
+ *
+ * This command (used by CI on Plugin Gallery repository) runs several checks on plugins.xml file:
+ * - Find all plugins and their releases in the XML file
+ * - Downloads all releases
+ * - Validates their MD5 checksum
+ */
 const shell = require('shelljs')
 const extractReleases = require('../utils/plugins/extractAllReleasesFromXml')
 const { writeFile } = require('../utils/files')
 const { info, error } = require('../utils/log')
 
-/**
- * Entry point for validate-all-releases command
- */
 module.exports = async args => {
   try {
     const inputFilePath = getFilePathFromArgs(args)

src/validate-new-release/extractReleaseDataFromDiff.js

@@ -1,6 +1,15 @@
 /**
- * scraps a fragment of xml to get the package url, MD5 etc..
+ * @file src/validate-new-release/extractReleaseDataFromDiff.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
  * @param {string} lines the diffed lines showing what changed in a plugins.xml file
+ *
+ * @brief Helper function to extract release data from a diff
+ *
+ * The function parses the output of a diff to find the package information
+ * (its url and MD5 namely)
  */
 const extractReleaseData = lines => {
   const { groups: { package } = {} } =

src/validate-new-release/index.js

@@ -1,3 +1,19 @@
+/**
+ * @file src/validate-new-release/index.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ *
+ * @brief Entry point for validate-new-release command
+ *
+ * This command runs on Git checkout of Plugin Gallery repository
+ * and validates new releases added to the file. Some of the checks:
+ * - Extracts the release and md5 data from diff
+ * - Downloads the package specified in the release
+ * - Validates the MD5 of the package downloaded
+ * - Checks the contents of the tar file of the package are valid
+ */
 const shell = require('shelljs')
 const downloadPackage = require('../utils/downloadPackage')
 const extractReleaseDataFromDiff = require('./extractReleaseDataFromDiff')

src/validate-new-release/validateTarContents.js

@@ -1,10 +1,19 @@
+/**
+ * @file src/validate-new-release/validateTarContents.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ *
+ * @brief Helper function to validate the conents of package
+ *
+ * Validates the contents of tarball, namely it checks whether a downloaded package
+ * contains one folder matching the plugin name
+ */
 const shell = require('shelljs')
 const { log } = require('../utils/log')
 const extractAllReleasesFromXml = require('../utils/plugins/extractAllReleasesFromXml')
 
-/**
- * Validates the contents of tarball (checks that it contains one folder matching the plugin name)
- */
 module.exports = async (
   { tarFile, md5, packageUrl },
   pluginsFilePath = './plugins.xml'

src/version.js

@@ -1,3 +1,11 @@
+/**
+ * @file src/version.js
+ *
+ * Copyright (c) 2020 Simon Fraser University
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @brief Prints the current version of the command line tool (run with pkp-plugin version)
+ */
 const { info } = require('./utils/log')
 
 module.exports = args => {