Merge pull request #247 from VisLab/second-revision

Additional corrections of jsDoc for readthedocs

Author: VisLab

bids/types/tsv.js

@@ -12,7 +12,7 @@ import { IssueError } from '../../common/issues/issues'
 export class BidsTsvFile extends BidsFile {
   /**
    * This file's parsed TSV data.
-   * @type {Map[]>}
+   * @type {Map[]}
    */
   parsedTsv
   /**
@@ -37,7 +37,7 @@ export class BidsTsvFile extends BidsFile {
    * @todo This interface is provisional and subject to modification in version 4.0.0.
    *
    * @param {string} name The name of the TSV file.
-   * @param {{headers: string[], rows: string[][]}|Map[]>|string} tsvData This file's TSV data.
+   * @param {{headers: string[], rows: string[][]|Map[]|string} tsvData This file's TSV data.
    * @param {object} file The file object representing this file.
    * @param {string[]} potentialSidecars The list of potential JSON sidecars.
    * @param {object} mergedDictionary The merged bidsFile data.

bids/validate.js

@@ -7,7 +7,7 @@ import { generateIssue } from '../common/issues/issues'
  *
  * @param {BidsDataset} dataset The BIDS dataset.
  * @param {SchemasSpec} schemaDefinition The version spec for the schema to be loaded.
- * @returns {Promise of BidsIssue[]} Any issues found.
+ * @returns {Promise} A promise for list of Any issues found.
  */
 export async function validateBidsDataset(dataset, schemaDefinition) {
   const validator = new BidsHedValidator(dataset, schemaDefinition)

bids/validator/tsvValidator.js

@@ -331,7 +331,7 @@ export class BidsHedTsvParser {
   /**
    * Generate a list of rows with column-to-value mappings.
    *
-   * @returns {Map[]} A list of single-row column-to-value mappings.
+   * @returns {Array.Map} A list of single-row column-to-value mappings.
    * @private
    */
   _generateHedRows() {

common/issues/issues.js

@@ -63,8 +63,8 @@ export class Issue {
    */
   message
   /**
-   * The parameters to the error message template.
-   * @type {Object<string, (string|number[])>}
+   * The parameters to the error message template. Object with string and map parameters.
+   * @type {Object}
    */
   parameters
 
@@ -73,7 +73,7 @@ export class Issue {
    * @param {string} internalCode The internal error code.
    * @param {string} hedCode The HED 3 error code.
    * @param {string} level The issue level (error or warning).
-   * @param {Object<string, (string|number[])>} parameters The error string parameters.
+   * @param {Object} parameters The error string parameters.
    */
   constructor(internalCode, hedCode, level, parameters) {
     this.internalCode = internalCode
@@ -134,7 +134,7 @@ export class Issue {
    * Return a tuple with a boolean denoting overall validity and all issues.
    *
    * @param {Issue[]} issues A list of issues.
-   * @returns {[boolean, Issue[]]} Whether the validation succeeded (i.e. any errors were found), and all issues (both errors and warnings).
+   * @returns {boolean, Issue[]} Whether the validation succeeded (i.e. any errors were found), and all issues (both errors and warnings).
    */
   static issueListWithValidStatus(issues) {
     return [!issues.some((issue) => issue.isError()), issues]
@@ -145,7 +145,7 @@ export class Issue {
  * Generate a new issue object.
  *
  * @param {string} internalCode The internal error code.
- * @param {Object<string, (string|number[])>} parameters The error string parameters.
+ * @param {Object} parameters The error string parameters.
  * @returns {Issue} An object representing the issue.
  */
 export const generateIssue = function (internalCode, parameters) {

docs/source/bids.types.rst

@@ -1,31 +1,31 @@
 types
 ==============================
-.. js:autoclass:: BidsDataset
+.. js:autoclass:: dataset.BidsDataset
     :members:
 
-.. js:autoclass:: BidsFile
+.. js:autoclass:: file.BidsFile
     :members:
 
-.. js:autoclass:: BidsHedIssue
+.. js:autoclass:: issues.BidsHedIssue
     :members:
 
-.. js:autoclass:: BidsIssue
+.. js:autoclass:: issues.idsIssue
     :members:
 
-.. js:autoclass:: BidsJsonFile
+.. js:autoclass:: json.BidsJsonFile
     :members:
 
-.. js:autoclass:: BidsSidecar
+.. js:autoclass:: json.BidsSidecar
     :members:
 
-.. js:autoclass:: BidsSidecarKey
+.. js:autoclass:: json.BidsSidecarKey
     :members:
 
-.. js:autoclass:: BidsTsvElement
+.. js:autoclass:: tsv.idsTsvElement
     :members:
 
-.. js:autoclass:: BidsTsvFile
+.. js:autoclass:: tsv.BidsTsvFile
     :members:
 
-.. js:autoclass:: BidsTsvRow
+.. js:autoclass:: tsv.BidsTsvRow
     :members:

parser/definitionManager.js

@@ -54,7 +54,7 @@ export class Definition {
    * @param {ParsedHedTag} tag - The parsed HEd tag whose details should be checked.
    * @param {Schemas} hedSchema - The HED schemas used to validate against.
    * @param {boolean} placeholderAllowed - If true then placeholder is allowed in the def tag.
-   * @returns {[string | null, Issue[]]} - The evaluated normalized definition string and any issues in the evaluation,
+   * @returns {string | null, Issue[]} - The evaluated normalized definition string and any issues in the evaluation,
    */
   evaluateDefinition(tag, hedSchema, placeholderAllowed) {
     // Check that the level of the value of tag agrees with the definition
@@ -106,7 +106,7 @@ export class Definition {
    *
    * @param {string} hedString - A list of string definitions.
    * @param {Schemas} hedSchemas - The HED schemas to use in creation.
-   * @returns { [Definition, Issue[]]} - The Definition list and any issues found.
+   * @returns {Definition, Issue[]} - The Definition list and any issues found.
    */
   static createDefinition(hedString, hedSchemas) {
     const [parsedString, issues] = parseHedString(hedString, hedSchemas, true, true)
@@ -122,7 +122,7 @@ export class Definition {
   /**
    * Create a definition from a ParsedHedGroup.
    * @param {ParsedHedGroup} group - The group to create a definition from.
-   * @returns { [Definition, Issue[]]} - The definition and any issues. (The definition will be null if issues.)
+   * @returns {Definition, Issue[]} - The definition and any issues. (The definition will be null if issues.)
    */
   static createDefinitionFromGroup(group) {
     const def = new Definition(group)
@@ -135,7 +135,7 @@ export class Definition {
 
 export class DefinitionManager {
   /**
-   * @type { Map<string, Definition>} - Definitions for this manager.
+   * @type {Map} - Definitions for this manager (string --> Definition).
    */
   definitions
 
@@ -183,7 +183,7 @@ export class DefinitionManager {
    * @param {ParsedHedString} hedString - A parsed HED string to be checked.
    * @param {Schemas} hedSchemas - Schemas to validate against.
    * @param {boolean} placeholderAllowed - If true then placeholder is allowed in the def tag.
-   * @returns {Issue []} - If there is no matching definition or definition applied incorrectly.
+   * @returns {Issue[]} - If there is no matching definition or definition applied incorrectly.
    */
   validateDefs(hedString, hedSchemas, placeholderAllowed) {
     const defTags = filterByTagName(hedString.tags, 'Def')
@@ -202,7 +202,7 @@ export class DefinitionManager {
    * @param {ParsedHedString} hedString - A parsed HED string to be checked.
    * @param {Schemas} hedSchemas - Schemas to validate against.
    * @param {boolean} placeholderAllowed - If true then placeholder is allowed in the def tag.
-   * @returns {Issue []} - If there is no matching definition or definition applied incorrectly.
+   * @returns {Issue[]} - If there is no matching definition or definition applied incorrectly.
    */
   validateDefExpands(hedString, hedSchemas, placeholderAllowed) {
     //Def-expand tags should be rare, so don't look if there aren't any Def-expand tags
@@ -222,7 +222,7 @@ export class DefinitionManager {
    * @param {ParsedHedTag} tag - The tag to evaluate against the definitions.
    * @param {Schemas} hedSchemas - The schemas to be used to assist in the evaluation.
    * @param {boolean} placeholderAllowed - If true then placeholder is allowed in the def tag.
-   * @returns {[string, Issue[]]} - The evaluated definition contents with this tag and any issues.
+   * @returns {string, Issue[]} - The evaluated definition contents with this tag and any issues.
    *
    * Note: If the tag is not a Def or Def-expand, this returns null for the string and [] for the issues.
    */
@@ -277,7 +277,7 @@ export class DefinitionManager {
   /**
    * Find the definition associated with a tag, if any
    * @param {ParsedHedTag} tag - The parsed HEd tag to be checked.
-   * @returns {[Definition | null, Issue []]} - If there is no matching definition.
+   * @returns {Definition | null, Issue[]} - If there is no matching definition.
    */
   findDefinition(tag) {
     if (tag.schemaTag._name !== 'Def' && tag.schemaTag.name !== 'Def-expand') {
@@ -300,7 +300,7 @@ export class DefinitionManager {
    *
    * @param {string[]} defStrings - A list of string definitions.
    * @param {Schemas} hedSchemas - The HED schemas to use in creation.
-   * @returns { [Definition[], Issue[]]} - The Definition list and any issues found.
+   * @returns {Definition[], Issue[]} - The Definition list and any issues found.
    */
   static createDefinitions(defStrings, hedSchemas) {
     const defList = []

parser/parsedHedTag.js

@@ -154,7 +154,7 @@ export default class ParsedHedTag extends ParsedHedSubstring {
    *
    * @param {SchemaTag} schemaTag - The part of the tag that is in the schema.
    * @param {string} remainder - The leftover part.
-   * @returns {[SchemaUnit, string, string]} - The actual Unit, the unit string and the value string.
+   * @returns {SchemaUnit, string, string} - The actual Unit, the unit string and the value string.
    * @throws {IssueError} If parsing the remainder section fails.
    */
   _separateUnits(schemaTag, remainder) {

parser/parser.js

@@ -48,7 +48,7 @@ class HedStringParser {
 
   /**
    * Parse a full HED string.
-   * @returns {[ParsedHedString|null, Issue[]]} The parsed HED string and any parsing issues.
+   * @returns {ParsedHedString|null, Issue[]} The parsed HED string and any parsing issues.
    */
   parseHedString() {
     if (this.hedString === null || this.hedString === undefined) {
@@ -115,7 +115,7 @@ class HedStringParser {
    * @param {Schemas} hedSchemas The collection of HED schemas.
    * @param {boolean} definitionsAllowed - True if definitions are allowed
    * @param {boolean} placeholdersAllowed - True if placeholders are allowed
-   * @returns {[ParsedHedString[], Issue[]]} The parsed HED strings and any issues found.
+   * @returns {ParsedHedString[], Issue[]} The parsed HED strings and any issues found.
    */
   static parseHedStrings(hedStrings, hedSchemas, definitionsAllowed, placeholdersAllowed) {
     if (!hedSchemas) {
@@ -145,7 +145,7 @@ class HedStringParser {
  * @param {Schemas} hedSchemas - The collection of HED schemas.
  * @param {boolean} definitionsAllowed - True if definitions are allowed
  * @param {boolean} placeholdersAllowed - True if placeholders are allowed
- * @returns {[ParsedHedString, Issue[]]} - The parsed HED string and any issues found.
+ * @returns {ParsedHedString, Issue[]} - The parsed HED string and any issues found.
  */
 export function parseHedString(hedString, hedSchemas, definitionsAllowed, placeholdersAllowed) {
   return new HedStringParser(hedString, hedSchemas, definitionsAllowed, placeholdersAllowed).parseHedString()

parser/reservedChecker.js

@@ -161,7 +161,7 @@ export class ReservedChecker {
    *
    * @param {ParsedHedGroup} group - The enclosing tag group.
    * @param {ParsedHedTag} reservedTag - The reserved tag whose tag requirements are to be checked.
-   * @param { Object } requirements - The requirements for this reserved tag.
+   * @param {Object} requirements - The requirements for this reserved tag.
    * @returns {Issue[]} - Issues because
    * @private
    */
@@ -205,7 +205,7 @@ export class ReservedChecker {
    *
    * @param {ParsedHedGroup} group - The enclosing tag group.
    * @param {ParsedHedTag} reservedTag - The reserved tag whose tag requirements are to be checked.
-   * @param { Object } requirements - The requirements for this reserved tag.
+   * @param {Object} requirements - The requirements for this reserved tag.
    * @returns {Issue[]}
    * @private
    */
@@ -232,7 +232,7 @@ export class ReservedChecker {
    * @param {ParsedHedTag} reservedTag - The reserved tags whose requirements are used.
    * @param {Number | null} minLimit - The minimum number of non-def groups required or null if no requirement.
    * @param {Number} defAdjustment - Either 0 or 1 depending on whether a def-expand is included.
-   * @returns {Issue[]|*[]} - Returns an issue list if the count requirement is violated.
+   * @returns {Issue[]} - Returns an issue list if the count requirement is violated.
    * @private
    */
   _checkMinGroupCount(group, reservedTag, minLimit, defAdjustment) {

parser/splitter.js

@@ -34,7 +34,7 @@ export default class HedStringSplitter {
   /**
    * Split and parse a HED string into tags and groups.
    *
-   * @returns {[ParsedHedSubstring[], Issue[]]} The parsed HED string data and any issues found.
+   * @returns {ParsedHedSubstring[], Issue[]} The parsed HED string data and any issues found.
    */
   splitHedString() {
     if (this.hedString === null || this.hedString === undefined || typeof this.hedString !== 'string') {
@@ -56,7 +56,7 @@ export default class HedStringSplitter {
    *
    * @param {TagSpec[]} tagSpecs The tag specifications.
    * @param {GroupSpec} groupSpecs The group specifications.
-   * @returns {[ParsedHedSubstring[], Issue[]]} The parsed HED tags and any issues.
+   * @returns {ParsedHedSubstring[], Issue[]} The parsed HED tags and any issues.
    */
   _createParsedTags(tagSpecs, groupSpecs) {
     // Create tags from specifications