Skip to content

Integrate gitStream with JSDoc

JSDoc Examples:

Review JSDoc Changes

Review JSDoc Changes

Approve PRs that only contain changes to JSDoc and assign optional reviewers.

Review JSDoc

Configuration Description

Conditions (all must be true):

  • The PR only affects JavaScript and TypeScript files
  • The PR only contains changes to JSDoc content.

Automation Actions:

  • Assign the ORG/tech-writers team.
  • Apply a green 📓 JSDoc Only label
  • Approve the PR

Review JSDoc

# -*- mode: yaml -*-
manifest:
  version: 1.0
automations:
  #Assign PRs that only affect JSDocs to the technical writing team and add docs label
  review_jsdoc:
    if:
      - {{ source.diff.files | match(attr='diff', regex=r/\/*\*[\s\S]*?\//) | every }}
    run:
      - action: add-label@v1
        args:
            label: "📓JSDoc Only"
            color: {{ colors.green }}
      - action: add-reviewers@v1
        args:
          reviewers: [fourth-organization/tech-writers]
      - action: approve@v1

colors:
  green: '0e8a16'
Download this example as a CM file.

Review JSDoc Input Parameters

Review JSDoc Input Parameters

Warn PR authors when they change JavaScript function or constructor input parameters without updating JSDoc content.

Review JSDoc Input Parameters

Configuration Description

Conditions (all must be true):

  • The PR changes an input parameter in one or more JavaScript methods.
  • The PR lacks changes to ‘@param’ declarations.

Automation Actions:

  • Post a comment warning the user to review the method’s JSDoc to identify necessary updates.

Review JSDoc Input Parameters

# -*- mode: yaml -*-
manifest:
  version: 1.0
automations:
  review_jsdoc_input: 
    if:  
      - {{ source.diff.files | matchDiffLines(regex=r/.*\s@param/) | nope }}
      - {{ source.diff.files | matchDiffLines(regex=r/\((?:.*\:.*\))/) | some }}

    run:
      - action: add-comment@v1
        args: 
          comment: | 
              This PR appears to modify method input parameters, but is missing JSDoc changes. Please check to ensure no JSDoc changes are necessary.
Download this example as a CM file.

Review JSDoc for Large Changes

Review JSDoc for Large Changes

Require more extensive reviews for large JavaScript changes that lack JSDoc updates.

Review JSDoc for Large changes

Configuration Description

Conditions (all must be true):

  • The PR changes more than 25% of a JavaScript class.

Automation Actions:

  • Post a comment asking the author to review all relevant JSDoc to identify necessary updates.
  • Require a review from the ORG/tech-writers team.
  • Apply a yellow ⚠️ Missing JSDoc Label

Review JSDoc

# -*- mode: yaml -*-
manifest:
  version: 1.0
automations:
  #Require more extensive reviews for large Javascript changes that lack JSDoc updates.
  review_jsdoc_large:
    if:
      - {{ changes.ratio > 25}}
      - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
    run: 
      - action: add-label@v1
        args:
          label: "⚠️ No JSDoc"
          color: {{ colors.yellow }}
      - action: add-comment@v1
        args: 
          comment: | 
            This PR makes major changes to JavaScript classes, but is missing updates to JSDoc. Please double check for any necessary JSDoc updates.

      - action: add-reviewers@v1
        args:
          reviewers: [fourth-organization/tech-writers]

changes:
  # Sum all the lines added/edited in the PR
  additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
  # Sum all the line removed in the PR
  deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
  # Calculate the ratio of new code
  ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}

colors:
  yellow: 'fbca04'
Download this example as a CM file.

Enforce JSDoc for New JavaScript Classes

Enforce JSDoc for New JavaScript Classes

Require JSDoc for all new JavaScript classes.

Enforce JSDoc for New JavaScript Classes

Configuration Description

Conditions (all must be true):

  • The PR creates a new JavaScript class.
  • The PR lacks JSDoc content.

Automation Actions:

  • Request changes and post a comment explaining that JSDoc is required
  • Apply a yellow ⚠️ Missing JSDoc label.

Enforce JSDoc for New JavaScript Classes

# -*- mode: yaml -*-
manifest:
  version: 1.0
automations:
  review_jsdoc_new_class: 
    if:  
        - {{ is.javascript and is.new }} 
        - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
    run:
      - action: add-label@v1
        args:
          label: "⚠️ Missing JSDoc"
          color: {{ colors.yellow }}
      - action: request-changes@v1
        args: 
          comment: | 
            JSDoc is required for all JavaScript classes. Please add JSDoc to all new classes in this PR.

is:
    javascript: {{ files | extensions | match(list=['js', 'ts']) | every }}
    new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}

colors:
  yellow: 'fbca04'
Download this example as a CM file.

Special thanks to Boemo W Mmopelwa for help with these examples.