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.
Rationale
Contributors are frequently submitting PRs to the processing-website repository with manual edits to auto-generated
.jsonfiles. This leads to confusion and unnecessary work. See for example: https://github.com/processing/processing-website/pull/471 and https://github.com/processing/processing-website/pull/524.Proposed solution
To prevent confusion and incorrect manual edits to auto-generated
.jsonfiles, prepend a prominent warning to the generated.jsonfiles. 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:
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