JavaDoc Integrations

[BenLloydPearson]

Enforce Javadoc Requirements for New Classes

Automation Name: review_new_class_javadoc

When someone creates a new Java class, request changes if the class doesn't meet JavaDoc requirements

Conditions (all must be true):

• The PR creates a new Java class.
  • {{ is.java and is.new | some }}
• The PR lacks Javadoc content. Use this regex: to detect:
  • \/\*\*[\s\S]*?@param[\s\S]*?@return[\s\S]*?\*\/

Include this custom expression:

is:
    java: {{ files | extensions | match(term='java') }}
    new: {{ source.diff.files | map(attr='original_file') | match(term='/dev/null') }}

Automation Actions:

• Request changes, and post a comment explaining that Javadoc is required
  • Javadoc is required for all Java classes. Please add Javadocs to all new classes in this PR.
• Apply a “⚠️ Missing Javadoc” label.

Review Javadoc Changes

Automation Name: review_javadoc

Assign PRs that only affect JavaDocs to the technical writing team and label the PR as a docs change

Conditions (all must be true):

• The PR only contains changes to Javadoc content. Use this regex:
  • \/\*\*[\s\S]*?\*\/

Automation Actions:

• Assign the my-organization/tech-writersteam.
• Apply a green “📓Javadoc Only” label
• Approve the PR

Review Javadoc Input Parameters

Automation Name: review_javadoc_input_parameters

If a PR modifies the input parameters for a Java method, but not the associated JavaDocs, request changes to update the JavaDocs.

Conditions (all must be true):

• The PR changes an input parameter in one or more Java methods. Use the following regex to detect this:
  • \b(public|protected|private|static|final|synchronized)?\s+(static|final|synchronized)?\s+(\w+<.*\>|\w+\[\]|\w+|\void)\s+\w+\s*\(([^)]*)\)\s*\{
• The PR lacks changes to ‘@param’ declarations. Use the following regex to detect this:
  • \* @param

Automation Actions:

• Post a comment warning the user to review the method’s Javadoc to identify necessary updates.
  • This PR modifies method input parameters, but is missing Javadoc changes. Please check to ensure no Javadoc changes are necessary.

Note: This example may not trigger for methods with annotations, methods that throw exceptions, multi-line method definitions, and other non-standard use cases.

Review Javadoc for Large Changes

Automation Name: review_javadoc_large

Require more extensive reviews for large Java changes that lack Javadoc updates.

Conditions (all must be true):

• The PR changes more than 25% of a Java class.
  • Use this example as a starting point.
• The PR lacks Javadoc changes.

Automation Actions:

• Post a comment asking the author to review all relevant Javadoc to identify necessary updates.
  • This PR makes major changes to Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.
• Require a review from the my-organization/tech-writers team.
• Apply a yellow ‘⚠️ No Javadoc’ Label

Additional Resources

Here are some additional examples you should incorporate into these automations:

• Colors custom expression - Use for all automations that implement color-coded labels. Only include the colors that are used in the automation.

[tresat]

These would be great examples to see.

[BenLloydPearson]

https://docs.gitstream.cm/integrations/javadoc/