Introduction to Skript's Documentation Annotations

This is a tutorial for addon devs on how to use Skript's built in annotations for your own documentation. By using Skript annotations, you will avoid the need to manually build/add you syntax elements one by one to website such as Skript Hub!

These annotations are best used with a Skript Documentation Tool such as the Skript Hub Docs Tool!

Getting Started

This guide will assume that you already have a working addon with a syntax element ready to go. This guide also assumes that you are depending on a version of Skript greater than 2.2-dev37.

All these annotations are optional, however it is recommended to use at least the Name and Description annotations.

Annotations

NoDoc

@NoDoc

This annotation is used to don't show the syntax element in documentations. Even the code patterns won't be shown. Example for this can be found here: ExprEventExpression in SkriptLang/Skript

Name

@Name("Example Syntax Element")

The display name or title of the syntax element.

Description

@Description({"This is where you can place all your info about the syntax element",
        "This will be a new line on most services"})

The description of the syntax element. Most sites/tools will allow you to use a markdown format for your docs.

Since

@Since("1.0, 1.1 (other feature)")

Since lets you tell users how long a feature has been in your addon. The Since annotation takes just a string, so you can also put very small notes.

Requirements

@RequiredPlugins({"requirement 1", "requirement 2"})

Lets you specify any external things needed to use the syntax element. The annotation is named as "RequiredPlugins" but Skript itself started using it for other things such as Paper.

Examples

@Examples({"example code for the syntax element."})

Example usage code for a syntax element. The array of strings will be separated by new lines on most services.

Documentation Id

@DocumentationId("NewDocumentationID")

Lets you manually specify an ID for a syntax element. Behavior may vary depending on the documentation generating tool.

Full Examples

Example 1

package ch.njol.skript.effects;

import ...

@Name("Cancel Command Cooldown")
@Description({"Only usable in command events. Makes it so the current command usage isn't counted towards the cooldown."})
@Examples({
        "command /nick <text>:",
        "\texecutable by: players",
        "\tcooldown: 10 seconds",
        "\ttrigger:",
        "\t\tif length of arg-1 is more than 16:",
        "\t\t\t# Makes it so that invalid arguments don't make you wait for the cooldown again",
        "\t\t\tcancel the cooldown",
        "\t\t\tsend \"Your nickname may be at most 16 characters.\"",
        "\t\t\tstop",
        "\t\tset the player's display name to arg-1"
})
@Since("2.2-dev34")
public class EffCancelCooldown extends Effect {
...
}

EffCancelCooldown in SkriptLang/Skript

Example 2

Skript.registerEvent("*Periodical", EvtPeriodical.class, ScheduledEvent.class, "every %timespan% in [world[s]] %worlds%")
                .description("An event that is called periodically.")
                .examples("every 2 seconds in \"world\"",
                        "every minecraft hour in \"flatworld\"",
                        "every ticks in \"world\" #can cause lag (depends on the code in this trigger)",
                        "every minecraft days in \"plots\"")
                .since("1.0")
                .documentationID("eventperiodical");

EvtPeriodical in SkriptLang/Skript

Example 3

@Name("Hover List")
@Description({"The list when you hover on the player counts of the server in the server list.",
        "This can be changed using texts or players in a <a href='events.html#server_list_ping'>server list ping</a> event only. " +
        "Adding players to the list means adding name of the players.",
        "And note that, for example if there are 5 online players (includes <a href='#ExprOnlinePlayersCount'>fake online count</a>) " +
        "in the server and the hover list is set to 3 values, Minecraft will show \"... and 2 more ...\" at end of the list."})
@Examples({"on server list ping:",
        "   clear the hover list",
        "   add \"&lt;light green>Welcome to the <orange>Minecraft &lt;light green>server!\" to the hover list",
        "   add \"\" to the hover list # A blank line",
        "   add \"&lt;light red>There are <orange>%online players count% &lt;light red>online players!\""})
@Since("2.3")
@RequiredPlugins("Paper 1.12.2 or newer")
@Events("server list ping")

ExprHoverList in SkriptLang/Skript

Example 4

@Name("Money")
@Description("How much virtual money a player has (can be changed). This expression requires Vault and a compatible economy plugin to be installed.")
@Examples({"message \"You have %player's money%\" # the currency name will be added automatically",
        "remove 20$ from the player's balance # replace '$' by whatever currency you use",
        "add 200 to the player's account # or omit the currency alltogether"})
@Since("2.0")

ExprBalance in SkriptLang/Skript