Skip to content

Conversation

Efnilite
Copy link
Member

@Efnilite Efnilite commented Aug 6, 2025

Problem

  • The docs.json can only be generated for Skript.
  • The return types of expressions are not mentioned in docs.json.
  • Events gathered from the @Events annotation do not follow the docs.json spec.
  • StructEvent does not have docs.

Solution

The `docs.json` can only be generated for Skript. JSONGenerator has been modified to allow creating an instance of JSONGenerator based on a SkriptAddon instance. To this extent, the `skriptVersion` property has been replaced with the `source` property.
"source": {
  "name": "Skript",
  "version": "2.12.1"
},

JSONGenerator also now uses the new Registration API to get all syntax registered by a specific addon.

Because this makes JSONGenerator not follow the DocumentationGenerator pattern, and since HTMLGenerator will soon be obselete, DocumentationGenerator has been deprecated, alongside JSONGenerator#generate().

The return types of expressions are not mentioned in `docs.json`. A new `returns` property has been added to expressions which determine what types an expression can return. This is currently only limited expressions that have a constant return type (i.e. not dependent on the input of the expression).
Events gathered from the `@Events` annotation do not follow the `docs.json` spec. Given that the source events cannot be gathered from the contents of the `@Events` annotation, currently, the id of the event and the name of the event are the same. Given `@Events({"x", "y"})`, the resulting json code would be:
"events": [
  { 
    "id": "x",
    "name": "x"
  },
  {
    "id": "y",
    "name": "y"
  }
]

This will be properly integrated when #7668 gets merged.

StructEvent does not have docs. Added docs.

Testing Completed

Manual testing.

Supporting Information

Breaking changes

  • Updated the JSONGenerator version to 2.0.
  • Removed the skriptVersion property and replaced it with the source property, which details the addon that this file was generated from.
  • Events gathered from the @Events annotation are now stored with an id and name, instead of as a plain string.
  • Renamed the returnType property for functions to an array called returns, similar to the new returns property on expressions.
  • Renamed the classes array to types.

Completes: #7680
Related: none

@Efnilite Efnilite added the enhancement Feature request, an issue about something that could be improved, or a PR improving something. label Aug 6, 2025
@Efnilite Efnilite added the documentation Related to Skript's official documentation. label Aug 6, 2025
@Efnilite Efnilite requested a review from a team as a code owner August 6, 2025 18:39
@Efnilite Efnilite added the breaking changes Pull or feature requests that contain breaking changes (API, syntax, etc.) label Aug 6, 2025
@skriptlang-automation skriptlang-automation bot added the needs reviews A PR that needs additional reviews label Aug 6, 2025
@Efnilite Efnilite moved this to In Review in 2.13 Releases Aug 6, 2025
@Efnilite Efnilite changed the title JSONGenerators for addons and docs.json improvements JSONGenerator for addons and docs.json improvements Aug 6, 2025
@APickledWalrus APickledWalrus self-requested a review August 6, 2025 21:30
Copy link
Member

@APickledWalrus APickledWalrus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good work here

@Efnilite Efnilite requested a review from APickledWalrus August 7, 2025 14:41
@skriptlang-automation skriptlang-automation bot removed the needs reviews A PR that needs additional reviews label Aug 10, 2025
@Efnilite Efnilite requested a review from a team as a code owner August 11, 2025 13:32
@Efnilite Efnilite requested a review from sovdeeth August 20, 2025 18:38
Copy link
Member

@APickledWalrus APickledWalrus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking really good, just a few things

@github-project-automation github-project-automation bot moved this from In Review to Awaiting Merge in 2.13 Releases Aug 24, 2025
@skriptlang-automation skriptlang-automation bot added the feature-ready A PR/issue that has been approved, tested and can be merged/closed in the next feature version. label Aug 29, 2025
@Efnilite Efnilite merged commit 2826897 into dev/feature Sep 17, 2025
6 of 39 checks passed
@github-project-automation github-project-automation bot moved this from Awaiting Merge to Done - Awaiting Release in 2.13 Releases Sep 17, 2025
@skriptlang-automation skriptlang-automation bot added the completed The issue has been fully resolved and the change will be in the next Skript update. label Sep 17, 2025
@Efnilite Efnilite deleted the feature/json-addon branch September 17, 2025 20:07
@skriptlang-automation skriptlang-automation bot removed the feature-ready A PR/issue that has been approved, tested and can be merged/closed in the next feature version. label Sep 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
breaking changes Pull or feature requests that contain breaking changes (API, syntax, etc.) completed The issue has been fully resolved and the change will be in the next Skript update. documentation Related to Skript's official documentation. enhancement Feature request, an issue about something that could be improved, or a PR improving something.
Projects
Status: Done - Awaiting Release
Development

Successfully merging this pull request may close these issues.

4 participants