Rationale

Contributors are frequently submitting PRs to the processing-website repository with manual edits to auto-generated .json files. This leads to confusion and unnecessary work. See for example: processing/processing-website#471 and processing/processing-website#524.

Proposed solution

To prevent confusion and incorrect manual edits to auto-generated .json files, prepend a prominent warning to the generated .json files. The warning should explain that the files should not be edited manually and provide a link to the documentation. Optionally it could also link to the file containing the corresponding JavaDoc annotation.

A possible message would be:

// WARNING: This file is auto-generated. DO NOT EDIT MANUALLY.
// Changes to this documentation should be made in the corresponding JavaDoc annotations.
// For more information, refer to the Doclet script documentation: https://github.com/processing/processing-doclet/blob/main/README.md
// The source for this file is located at [link to corresponding file]

Edit: I realize the JSON standard doesn't allow comments but we could strip the comments before feeding the files to the parser if it causes issues.

References

• Processing Website Readme on JavaDoc annotations
• Doclet Script Documentation