Use @Example annotations instead of @Examples by bluelhf · Pull Request #8224 · SkriptLang/Skript

bluelhf · 2025-10-03T19:02:59Z

Previously at #8222, closed because PR was ahead base.

This PR moves many syntaxes to use @Example-annotations instead of @Examples. The goal of this PR is to move all Skript syntaxes towards the new repeatable annotations. This results in cleaner generated JSON, with unambiguous data when multiple examples are present.

Warning

This pull request was, due to its scale and simplicity, made in large part using agentic Copilot. Copilot has proven to be quite bad at tasks like programming and understanding language, and mistakes are expected.

Testing Completed

I have generated the docs and looked for errors as well as verified every example by hand.

Note about line endings

End-of-line characters are not present when examples are defined in a single line. We should consider adapting JSONGenerator to insert an end-of-line character at the end of each example if it is missing. This way, all examples consist of POSIX-compliant 'lines', which always end in an end-of-line character.

State of pull request

All syntaxes using @Examples migrated
All syntaxes verified independently (thanks @sovdeeth and @APickledWalrus!)

src/main/java/ch/njol/skript/expressions/ExprBlock.java

src/main/java/org/skriptlang/skript/bukkit/displays/text/EffTextDisplayDropShadow.java

@sovdeeth

applies code suggestions from @sovdeeth Co-authored-by: sovdee <10354869+sovdeeth@users.noreply.github.com>

sovdeeth

only looked through conditions

src/main/java/ch/njol/skript/conditions/CondIsClimbing.java

src/main/java/ch/njol/skript/conditions/CondIsSkriptCommand.java

src/main/java/ch/njol/skript/conditions/CondMatches.java

…o Example this changes the rest of the vanilla Skript syntaxes. the old Examples annotation is left there because addons probably use it still

thanks, sovde ! Co-authored-by: sovdee <10354869+sovdeeth@users.noreply.github.com>

sovdeeth

400/681

src/main/java/ch/njol/skript/conditions/CondChatFiltering.java

src/main/java/ch/njol/skript/conditions/CondElytraBoostConsume.java

src/main/java/ch/njol/skript/effects/EffExit.java

src/main/java/ch/njol/skript/effects/EffToggleCanPickUpItems.java

src/main/java/ch/njol/skript/effects/EffTransform.java

src/main/java/ch/njol/skript/expressions/ExprAge.java

src/main/java/ch/njol/skript/expressions/ExprCodepoint.java

src/main/java/ch/njol/skript/expressions/ExprCommandInfo.java

src/main/java/ch/njol/skript/expressions/ExprCompassTarget.java

sovdeeth

555/680

src/main/java/ch/njol/skript/expressions/ExprDomestication.java

src/main/java/ch/njol/skript/expressions/ExprEntitySnapshot.java

src/main/java/ch/njol/skript/expressions/ExprMetadata.java

src/main/java/ch/njol/skript/expressions/ExprPassenger.java

src/main/java/ch/njol/skript/expressions/ExprRound.java

applies changes from code review Co-authored-by: sovde <10354869+sovdeeth@users.noreply.github.com>

sovdeeth

680/680!

src/main/java/ch/njol/skript/expressions/ExprValue.java

src/main/java/ch/njol/skript/expressions/ExprXYZComponent.java

src/main/java/ch/njol/skript/hooks/regions/expressions/ExprMembersOfRegion.java

Co-authored-by: sovde <10354869+sovdeeth@users.noreply.github.com>

APickledWalrus

it didn't let me suggest sometimes

src/main/java/ch/njol/skript/effects/EffCancelCooldown.java

src/main/java/ch/njol/skript/effects/EffChange.java

src/main/java/ch/njol/skript/effects/EffSort.java

src/main/java/ch/njol/skript/expressions/ExprFallDistance.java

src/main/java/ch/njol/skript/expressions/ExprLevelProgress.java

src/main/java/ch/njol/skript/expressions/ExprUUID.java

src/main/java/ch/njol/skript/expressions/ExprVectorCylindrical.java

src/main/java/ch/njol/skript/hooks/chat/expressions/ExprPrefixSuffix.java

src/main/java/ch/njol/skript/hooks/regions/conditions/CondCanBuild.java

src/main/java/ch/njol/skript/hooks/regions/expressions/ExprRegionsAt.java

src/main/java/ch/njol/skript/structures/StructOptions.java

APickledWalrus

Great work!

sovdeeth requested changes Oct 6, 2025

View reviewed changes

src/main/java/ch/njol/skript/expressions/ExprBlock.java Outdated Show resolved Hide resolved

src/main/java/org/skriptlang/skript/bukkit/displays/text/EffTextDisplayDropShadow.java Outdated Show resolved Hide resolved

bluelhf marked this pull request as ready for review October 19, 2025 00:21

bluelhf requested review from a team and UnderscoreTud as code owners October 19, 2025 00:21

bluelhf requested review from Absolutionism and removed request for a team October 19, 2025 00:21

bluelhf and others added 4 commits October 19, 2025 03:29

refactor: use @example annotations instead of @examples

de4d7ec

fix: address code suggestions

9aebec8

refactor(docs): continue work on Examples->Example migration

c90cb68

fix(docs): indent examples properly

1c29f27

applies code suggestions from @sovdeeth Co-authored-by: sovdee <10354869+sovdeeth@users.noreply.github.com>

sovdeeth requested changes Oct 19, 2025

View reviewed changes

bluelhf added 2 commits October 19, 2025 03:40

refactor(docs): finish migrating syntaxes from Examples annotations t…

9cc6c80

…o Example this changes the rest of the vanilla Skript syntaxes. the old Examples annotation is left there because addons probably use it still

revert: swap skript-aliases back to old hash

332d649

bluelhf force-pushed the dev/examples-migration branch from 96dcf0f to 332d649 Compare October 19, 2025 00:51

chore(docs): apply code suggestions

1f59e03

thanks, sovde ! Co-authored-by: sovdee <10354869+sovdeeth@users.noreply.github.com>

bluelhf requested a review from sovdeeth October 19, 2025 01:24

bluelhf added 2 commits October 19, 2025 04:26

fix(docs): merge EffCopy examples into one

9299e93

fix(docs): remove extra quote

7b66b26

sovdeeth requested changes Oct 19, 2025

View reviewed changes

skriptlang-automation bot added the needs reviews A PR that needs additional reviews label Oct 19, 2025

fix(docs): improvements to examples

0b1124c

applies changes from code review Co-authored-by: sovde <10354869+sovdeeth@users.noreply.github.com>

sovdeeth requested changes Oct 19, 2025

View reviewed changes

fix(docs): example indentation

0dab641

Co-authored-by: sovde <10354869+sovdeeth@users.noreply.github.com>

sovdeeth approved these changes Oct 19, 2025

View reviewed changes

sovdeeth added enhancement Feature request, an issue about something that could be improved, or a PR improving something. documentation Related to Skript's official documentation. labels Oct 19, 2025

bluelhf and others added 2 commits November 5, 2025 03:44

Merge branch 'dev/patch' into dev/examples-migration

aa111ad

Merge branch 'dev/patch' into dev/examples-migration

12d7144

sovdeeth added this to 2.14 Releases Dec 10, 2025

sovdeeth moved this to In Review in 2.14 Releases Dec 10, 2025

APickledWalrus requested changes Dec 19, 2025

View reviewed changes

skriptlang-automation bot added needs reviews A PR that needs additional reviews and removed needs reviews A PR that needs additional reviews labels Dec 19, 2025

chore(docs): improve examples

8394764

sovdeeth mentioned this pull request Dec 28, 2025

starlight - use updated syntaxes.json (thanks blue!) SkriptLang/docs#8

Merged

sovdeeth requested changes Dec 28, 2025

View reviewed changes

src/main/java/ch/njol/skript/structures/StructOptions.java Show resolved Hide resolved

skriptlang-automation bot removed the needs reviews A PR that needs additional reviews label Dec 28, 2025

fix(docs): combine StructOptions example

9cac36f

APickledWalrus approved these changes Dec 29, 2025

View reviewed changes

APickledWalrus requested a review from sovdeeth December 29, 2025 01:18

sovdeeth approved these changes Dec 29, 2025

View reviewed changes

skriptlang-automation bot added the patch-ready A PR/issue that has been approved and is ready to be merged/closed for the next patch version. label Dec 29, 2025

github-project-automation bot moved this from In Review to Awaiting Merge in 2.14 Releases Dec 29, 2025

Merge branch 'dev/patch' into dev/examples-migration

9f50618

sovdeeth merged commit f969563 into SkriptLang:dev/patch Dec 31, 2025
5 checks passed

github-project-automation bot moved this from Awaiting Merge to Done - Awaiting Release in 2.14 Releases Dec 31, 2025

skriptlang-automation bot added completed The issue has been fully resolved and the change will be in the next Skript update. and removed patch-ready A PR/issue that has been approved and is ready to be merged/closed for the next patch version. labels Dec 31, 2025

bluelhf deleted the dev/examples-migration branch December 31, 2025 22:13

APickledWalrus moved this from Done - Awaiting Release to Done - Released in 2.14 Releases Jan 2, 2026

Uh oh!

Conversation

bluelhf commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing Completed

Note about line endings

State of pull request

Uh oh!

Uh oh!

Uh oh!

sovdeeth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sovdeeth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sovdeeth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sovdeeth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

APickledWalrus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

APickledWalrus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

bluelhf commented Oct 3, 2025 •

edited

Loading