Merge pull request #124 from VisLab/master

Updated the readthedocs again

.gitignore

@@ -3,3 +3,37 @@ node_modules
 .directory
 .idea
 dist/
+/venv/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Distribution / packaging
+.Python
+env/
+bin/
+build/
+develop-eggs/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+tests/scratch
+docs/_build

bids/tsvParser.js

@@ -12,7 +12,7 @@ const isContentfulRow = (row) => row && !/^\s*$/.test(row)
  * Parse a TSV file.
  *
  * @param {string} contents The contents of a TSV file.
- * @return {{headers: string[], rows: string[][]}} The parsed contents of the TSV file.
+ * @returns {{headers: string[], rows: string[][]}} The parsed contents of the TSV file.
  */
 function parseTSV(contents) {
   const content = {

bids/types.js

@@ -318,7 +318,7 @@ export class BidsIssue {
 
   /**
    * Whether this issue is an error.
-   * @return {boolean}
+   * @returns {boolean}
    */
   isError() {
     return bidsHedErrorCodes.has(this.code)

bids/utils.js

@@ -2,7 +2,7 @@
  * Determine whether a sidecar value has HED data.
  *
  * @param {object} sidecarValue A BIDS sidecar value.
- * @return {boolean} Whether the sidecar value has HED data.
+ * @returns {boolean} Whether the sidecar value has HED data.
  */
 export const sidecarValueHasHed = function (sidecarValue) {
   return sidecarValue !== null && typeof sidecarValue === 'object' && sidecarValue.HED !== undefined

bids/validate.js

@@ -9,7 +9,7 @@ import { generateIssue, Issue, IssueError } from '../common/issues/issues'
  *
  * @param {BidsDataset} dataset The BIDS dataset.
  * @param {object} schemaDefinition The version spec for the schema to be loaded.
- * @return {Promise<BidsIssue[]>} Any issues found.
+ * @returns {Promise<BidsIssue[]>} Any issues found.
  */
 export function validateBidsDataset(dataset, schemaDefinition) {
   return buildBidsSchemas(dataset, schemaDefinition).then(
@@ -29,7 +29,7 @@ export function validateBidsDataset(dataset, schemaDefinition) {
  *
  * @param {BidsDataset} dataset A BIDS dataset.
  * @param {Schemas} hedSchemas A HED schema collection.
- * @return {Promise<BidsIssue[]>|Promise<never>} Any issues found.
+ * @returns {Promise<BidsIssue[]>|Promise<never>} Any issues found.
  */
 function validateFullDataset(dataset, hedSchemas) {
   try {
@@ -52,7 +52,7 @@ function validateFullDataset(dataset, hedSchemas) {
  *
  * @param {BidsTsvFile} tsvFileData A BIDS TSV file.
  * @param {Schemas} hedSchemas A HED schema collection.
- * @return {BidsIssue[]} Any issues found.
+ * @returns {BidsIssue[]} Any issues found.
  */
 function validateBidsTsvFile(tsvFileData, hedSchemas) {
   const [hedStrings, tsvIssues] = parseTsvHed(tsvFileData)
@@ -69,7 +69,7 @@ function validateBidsTsvFile(tsvFileData, hedSchemas) {
  *
  * @param {BidsSidecar[]} sidecarData A collection of BIDS sidecars.
  * @param {Schemas} hedSchemas A HED schema collection.
- * @return {[boolean, BidsHedIssue[]]} Whether errors (as opposed to warnings) were founds, and all issues found.
+ * @returns {[boolean, BidsHedIssue[]]} Whether errors (as opposed to warnings) were founds, and all issues found.
  */
 function validateSidecars(sidecarData, hedSchemas) {
   const issues = []
@@ -94,7 +94,7 @@ function validateSidecars(sidecarData, hedSchemas) {
  *
  * @param {BidsEventFile[]} eventData A collection of BIDS event TSV files.
  * @param {Schemas} hedSchemas A HED schema collection.
- * @return {[boolean, BidsHedIssue[]]} Whether errors (as opposed to warnings) were founds, and all issues found.
+ * @returns {[boolean, BidsHedIssue[]]} Whether errors (as opposed to warnings) were founds, and all issues found.
  */
 function validateHedColumn(eventData, hedSchemas) {
   const issues = eventData.flatMap((eventFileData) => {
@@ -111,7 +111,7 @@ function validateHedColumn(eventData, hedSchemas) {
  * Combine the BIDS sidecar HED data into a BIDS TSV file's HED data.
  *
  * @param {BidsTsvFile} tsvFileData A BIDS TSV file.
- * @return {[string[], BidsIssue[]]} The combined HED strings for this BIDS TSV file, and all issues found during the combination.
+ * @returns {[string[], BidsIssue[]]} The combined HED strings for this BIDS TSV file, and all issues found during the combination.
  */
 function parseTsvHed(tsvFileData) {
   const hedStrings = []
@@ -177,7 +177,7 @@ function parseTsvHed(tsvFileData) {
  * @param {string[]} hedStrings The HED strings in the data collection.
  * @param {Schemas} hedSchemas The HED schema collection to validate against.
  * @param {BidsTsvFile} tsvFileData The BIDS event TSV file being validated.
- * @return {BidsHedIssue[]} Any issues found.
+ * @returns {BidsHedIssue[]} Any issues found.
  */
 function validateCombinedDataset(hedStrings, hedSchemas, tsvFileData) {
   const [, hedIssues] = validateHedDatasetWithContext(hedStrings, tsvFileData.mergedSidecar.hedStrings, hedSchemas, {
@@ -194,7 +194,7 @@ function validateCombinedDataset(hedStrings, hedSchemas, tsvFileData) {
  * @param {Schemas} hedSchemas The HED schema collection to validate against.
  * @param {Object} fileObject A BIDS-format file object used to generate {@link BidsHedIssue} objects.
  * @param {Object} settings Options to pass to {@link validateHedString}.
- * @return {BidsHedIssue[]} Any issues found.
+ * @returns {BidsHedIssue[]} Any issues found.
  */
 function validateStrings(hedStrings, hedSchemas, fileObject, settings) {
   const issues = []
@@ -218,7 +218,7 @@ function validateStrings(hedStrings, hedSchemas, fileObject, settings) {
  *
  * @param {IssueError|Issue[]} hedIssues One or more HED-format issues.
  * @param {Object} file A BIDS-format file object used to generate {@link BidsHedIssue} objects.
- * @return {BidsHedIssue[]} The passed issue(s) in BIDS-compatible format.
+ * @returns {BidsHedIssue[]} The passed issue(s) in BIDS-compatible format.
  */
 function convertHedIssuesToBidsIssues(hedIssues, file) {
   if (hedIssues instanceof IssueError) {

common/issues/issues.js

@@ -71,7 +71,7 @@ export class Issue {
   /**
    * Override of {@link Object.prototype.toString}.
    *
-   * @return {string} This issue's message.
+   * @returns {string} This issue's message.
    */
   toString() {
     return this.message
@@ -87,7 +87,7 @@ export class Issue {
  *
  * @param {string} internalCode The internal error code.
  * @param {Object<string, (string|number[])>} parameters The error string parameters.
- * @return {Issue} An object representing the issue.
+ * @returns {Issue} An object representing the issue.
  */
 export const generateIssue = function (internalCode, parameters) {
   const issueCodeData = issueData[internalCode] ?? issueData.genericError

common/schema/loader.js

@@ -14,7 +14,7 @@ import { fallbackFilePath, localSchemaList } from './config'
  * @param {SchemaSpec} schemaDef The description of which schema to use.
  * @param {boolean} useFallback Whether to use a bundled fallback schema if the requested schema cannot be loaded.
  * @param {boolean} reportNoFallbackError Whether to report an error on a failed schema load when no fallback was used.
- * @return {Promise<never>|Promise<[object, Issue[]]>} The schema XML data or an error.
+ * @returns {Promise<never>|Promise<[object, Issue[]]>} The schema XML data or an error.
  */
 export const loadSchema = function (schemaDef = null, useFallback = true, reportNoFallbackError = true) {
   const schemaPromise = loadPromise(schemaDef)
@@ -52,7 +52,7 @@ export const loadSchema = function (schemaDef = null, useFallback = true, report
  * @todo Rename to {@link loadSchema} in 4.0.0.
  *
  * @param {SchemaSpec} schemaDef The description of which schema to use.
- * @return {Promise<never>|Promise<[object, Issue[]]>} The schema XML data or an error.
+ * @returns {Promise<never>|Promise<[object, Issue[]]>} The schema XML data or an error.
  */
 export const loadSchemaFromSpec = function (schemaDef = null) {
   const schemaPromise = loadPromise(schemaDef)
@@ -66,7 +66,7 @@ export const loadSchemaFromSpec = function (schemaDef = null) {
  * Choose the schema Promise from a schema version or path description.
  *
  * @param {SchemaSpec} schemaDef The description of which schema to use.
- * @return {Promise<object>} The schema XML data or an error.
+ * @returns {Promise<object>} The schema XML data or an error.
  */
 const loadPromise = function (schemaDef) {
   if (schemaDef === null) {
@@ -87,7 +87,7 @@ const loadPromise = function (schemaDef) {
  * Load schema XML data from the HED GitHub repository.
  *
  * @param {SchemaSpec} schemaDef The standard schema version to load.
- * @return {Promise<object>} The schema XML data.
+ * @returns {Promise<object>} The schema XML data.
  */
 const loadRemoteSchema = function (schemaDef) {
   let url
@@ -103,7 +103,7 @@ const loadRemoteSchema = function (schemaDef) {
  * Load schema XML data from a local file.
  *
  * @param {string} path The path to the schema XML data.
- * @return {Promise<object>} The schema XML data.
+ * @returns {Promise<object>} The schema XML data.
  */
 const loadLocalSchema = function (path) {
   return loadSchemaFile(files.readFile(path), 'localSchemaLoadFailed', { path: path })
@@ -113,7 +113,7 @@ const loadLocalSchema = function (path) {
  * Load schema XML data from a bundled file.
  *
  * @param {SchemaSpec} schemaDef The description of which schema to use.
- * @return {Promise<object>} The schema XML data.
+ * @returns {Promise<object>} The schema XML data.
  */
 const loadBundledSchema = function (schemaDef) {
   return parseSchemaXML(localSchemaList.get(schemaDef.localName)).catch((error) => {
@@ -128,7 +128,7 @@ const loadBundledSchema = function (schemaDef) {
  * @param {Promise<string>} xmlDataPromise The Promise containing the unparsed XML data.
  * @param {string} issueCode The issue code.
  * @param {Object<string, string>} issueArgs The issue arguments passed from the calling function.
- * @return {Promise<object>} The parsed schema XML data.
+ * @returns {Promise<object>} The parsed schema XML data.
  */
 const loadSchemaFile = function (xmlDataPromise, issueCode, issueArgs) {
   return xmlDataPromise.then(parseSchemaXML).catch((error) => {
@@ -141,7 +141,7 @@ const loadSchemaFile = function (xmlDataPromise, issueCode, issueArgs) {
  * Parse the schema XML data.
  *
  * @param {string} data The XML data.
- * @return {Promise<object>} The schema XML data.
+ * @returns {Promise<object>} The schema XML data.
  */
 const parseSchemaXML = function (data) {
   return xml2js.parseStringPromise(data, { explicitCharkey: true })

common/schema/types.js

@@ -54,7 +54,7 @@ export class Schema {
    *
    * @param {string} tag The HED tag to check.
    * @param {string} tagAttribute The attribute to check for.
-   * @return {boolean} Whether this tag has this attribute.
+   * @returns {boolean} Whether this tag has this attribute.
    * @abstract
    */
   // eslint-disable-next-line no-unused-vars
@@ -84,7 +84,7 @@ export class Hed2Schema extends Schema {
    *
    * @param {string} tag The HED tag to check.
    * @param {string} tagAttribute The attribute to check for.
-   * @return {boolean} Whether this tag has this attribute.
+   * @returns {boolean} Whether this tag has this attribute.
    */
   tagHasAttribute(tag, tagAttribute) {
     return this.attributes.tagHasAttribute(tag, tagAttribute)
@@ -121,7 +121,7 @@ export class Hed3Schema extends Schema {
    *
    * @param {string} tag The HED tag to check.
    * @param {string} tagAttribute The attribute to check for.
-   * @return {boolean} Whether this tag has this attribute.
+   * @returns {boolean} Whether this tag has this attribute.
    */
   tagHasAttribute(tag, tagAttribute) {
     return this.entries.tagHasAttribute(tag, tagAttribute)
@@ -235,15 +235,15 @@ export class Schemas {
 
   /**
    * Whether this schema collection is for syntactic validation only.
-   * @return {boolean}
+   * @returns {boolean}
    */
   get isSyntaxOnly() {
     return this.generation === 0
   }
 
   /**
    * Whether this schema collection comprises HED 3 schemas.
-   * @return {boolean}
+   * @returns {boolean}
    */
   get isHed3() {
     return this.generation === 3

converter/__tests__/converter.spec.js

@@ -23,7 +23,7 @@ describe('HED string conversion', () => {
      * @param {Object<string, string>} expectedResults The expected results.
      * @param {Object<string, Issue[]>} expectedIssues The expected issues.
      * @param {function (Schema, string, string, number): [string, Issue[]]} testFunction The test function.
-     * @return {Promise<void>}
+     * @returns {Promise<void>}
      */
     const validatorBase = function (testStrings, expectedResults, expectedIssues, testFunction) {
       return hedSchemaPromise.then(([hedSchemas, issues]) => {
@@ -588,7 +588,7 @@ describe('HED string conversion', () => {
      * @param {Object<string, string>} expectedResults The expected results.
      * @param {Object<string, Issue[]>} expectedIssues The expected issues.
      * @param {function (Schemas, string): [string, Issue[]]} testFunction The test function.
-     * @return {Promise<void>}
+     * @returns {Promise<void>}
      */
     const validatorBase = function (testStrings, expectedResults, expectedIssues, testFunction) {
       return hedSchemaPromise.then(([hedSchemas, issues]) => {

converter/converter.js

@@ -9,7 +9,7 @@ const doubleSlashPattern = /[\s/]*\/+[\s/]*/g
  * Remove extra slashes and spaces from a HED string.
  *
  * @param {string} hedString The HED string to clean.
- * @return {string} The cleaned HED string.
+ * @returns {string} The cleaned HED string.
  */
 export const removeSlashesAndSpaces = function (hedString) {
   return hedString.replace(doubleSlashPattern, '/')
@@ -26,7 +26,7 @@ export const removeSlashesAndSpaces = function (hedString) {
  * @param {string} hedTag The HED tag to convert.
  * @param {string} hedString The full HED string (for error messages).
  * @param {number} offset The offset of this tag within the HED string.
- * @return {[string, Issue[]]} The long-form tag and any issues.
+ * @returns {[string, Issue[]]} The long-form tag and any issues.
  */
 export const convertTagToLong = function (schema, hedTag, hedString, offset) {
   const mapping = schema.mapping
@@ -127,7 +127,7 @@ export const convertTagToLong = function (schema, hedTag, hedString, offset) {
  * @param {string} hedTag The HED tag to convert.
  * @param {string} hedString The full HED string (for error messages).
  * @param {number} offset The offset of this tag within the HED string.
- * @return {[string, Issue[]]} The short-form tag and any issues.
+ * @returns {[string, Issue[]]} The short-form tag and any issues.
  */
 export const convertTagToShort = function (schema, hedTag, hedString, offset) {
   const mapping = schema.mapping
@@ -198,7 +198,7 @@ export const convertTagToShort = function (schema, hedTag, hedString, offset) {
  * @param {string} partialHedString The partial HED string to convert to long form.
  * @param {string} fullHedString The full HED string.
  * @param {number} offset The offset of the partial HED string within the full string.
- * @return {[string, Issue[]]} The converted string and any issues.
+ * @returns {[string, Issue[]]} The converted string and any issues.
  */
 export const convertPartialHedStringToLong = function (schema, partialHedString, fullHedString, offset) {
   let issues = []
@@ -233,7 +233,7 @@ export const convertPartialHedStringToLong = function (schema, partialHedString,
  * @param {Schema} schema The schema object containing a short-to-long mapping.
  * @param {string} hedString The HED tag to convert.
  * @param {function (Schema, string, string, number): [string, Issue[]]} conversionFn The conversion function for a tag.
- * @return {[string, Issue[]]} The converted string and any issues.
+ * @returns {[string, Issue[]]} The converted string and any issues.
  */
 const convertHedString = function (schema, hedString, conversionFn) {
   let issues = []
@@ -267,7 +267,7 @@ const convertHedString = function (schema, hedString, conversionFn) {
  *
  * @param {Schemas} schemas The schema container object containing short-to-long mappings.
  * @param {string} hedString The HED tag to convert.
- * @return {[string, Issue[]]} The long-form string and any issues.
+ * @returns {[string, Issue[]]} The long-form string and any issues.
  * @deprecated
  */
 export const convertHedStringToLong = function (schemas, hedString) {
@@ -279,7 +279,7 @@ export const convertHedStringToLong = function (schemas, hedString) {
  *
  * @param {Schemas} schemas The schema container object containing short-to-long mappings.
  * @param {string} hedString The HED tag to convert.
- * @return {[string, Issue[]]} The short-form string and any issues.
+ * @returns {[string, Issue[]]} The short-form string and any issues.
  * @deprecated
  */
 export const convertHedStringToShort = function (schemas, hedString) {

converter/issues.js

@@ -10,7 +10,7 @@ import { generateIssue } from '../common/issues/issues'
  * @param {string} hedString The source HED string.
  * @param {object} parameters The parameters to the format string.
  * @param {number[]} bounds The bounds of the problem tag.
- * @return {Issue} The issue object.
+ * @returns {Issue} The issue object.
  */
 export default function (code, hedString, parameters = {}, bounds = []) {
   parameters.tag = hedString.slice(bounds[0], bounds[1])

converter/schema.js

@@ -9,7 +9,7 @@ import { generateIssue, IssueError } from '../common/issues/issues'
  * Build a short-long mapping object from schema XML data.
  *
  * @param {SchemaEntries} entries The schema XML data.
- * @return {Mapping} The mapping object.
+ * @returns {Mapping} The mapping object.
  */
 export const buildMappingObject = function (entries) {
   /**
@@ -48,7 +48,7 @@ export const buildMappingObject = function (entries) {
  * Build a schema container object containing a short-long mapping from a base schema version or path description.
  *
  * @param {{path: string?, version: string?}} schemaDef The description of which schema to use.
- * @return {Promise<never>|Promise<Schemas>} The schema container object or an error.
+ * @returns {Promise<never>|Promise<Schemas>} The schema container object or an error.
  * @deprecated
  */
 export const buildSchema = (schemaDef) => validatorBuildSchema(schemaDef)

converter/splitHedString.js

@@ -4,7 +4,7 @@ const tagDelimiters = new Set([',', '(', ')', '~'])
  * Split a HED string into delimiters and tags.
  *
  * @param {string} hedString The HED string to split.
- * @return {Array[]} A list of string parts. The boolean is true if the part is
+ * @returns {Array[]} A list of string parts. The boolean is true if the part is
  * a tag and false if it is a delimiter. The numbers are the bounds of the part.
  */
 export default function splitHedString(hedString) {