[Brigadier] Document custom arguments

[Strokkur424]

Note

This issue is part of a series of issues regarding the extension of the Paper documentation regarding Paper's Brigadier API.

In addition to custom argument suggestions, normal custom arguments should also be documented. This would have two parts. For once, the standard CustomArgumentType<T, N> and its methods should be documented and given an example to. Secondly, CustomArgumentTtype.Converted<T, N> should also be documented.

One point to definitely mention is the inability to provide the red client-side text in case the argument is invalid, since for that the client needs to do validation, which custom argument types do not do, since they actually only send their native type (and on tab complete possible suggestions) to the client, not their parser.

For the standard custom argument type, a MiniMessage-string styled Component argument could be created, since the native one expects its input as JSON, which is not very user-friendly.

For the converted one, we can provide a similar setup like the old documentation: using ice cream flavors. Here, we can link to command syntax exceptions. A possible class to showcase and describe could be this one:

@NullMarked
public class IceCreamArgument implements CustomArgumentType.Converted<IceCreamArgument.IceCream, String> {

    @Override
    public IceCream convert(String nativeType) throws CommandSyntaxException {
        for (IceCream iceCream : IceCream.values()) {
            if (iceCream.name().equalsIgnoreCase(nativeType)) {
                return iceCream;
            }
        }

        final Message exceptionMessage = new LiteralMessage("Unknown ice cream flavor: " + nativeType);
        throw new CommandSyntaxException(new SimpleCommandExceptionType(exceptionMessage), exceptionMessage);
    }

    @Override
    public ArgumentType<String> getNativeType() {
        return StringArgumentType.word();
    }

    @Override
    public <S> CompletableFuture<Suggestions> listSuggestions(CommandContext<S> context, SuggestionsBuilder builder) {
        for (IceCream iceCream : IceCream.values()) {
            if (!iceCream.name().toLowerCase().startsWith(builder.getRemainingLowerCase())) {
                continue;
            }

            builder.suggest(iceCream.name().toLowerCase());
        }

        return builder.buildFuture();
    }

    public enum IceCream {
        VANILLA,
        CHOCOLATE,
        STRAWBERRY
    }
}

Including its usage:

return Commands.literal("order-icecream")
    .then(Commands.argument("flavor", new IceCreamArgument())
        .executes(ctx -> {
            final IceCreamArgument.IceCream flavor = ctx.getArgument("flavor", IceCreamArgument.IceCream.class);

            ctx.getSource().getSender().sendRichMessage("<light_purple>You ordered: <dark_purple><flavor></dark_purple>!",
                Placeholder.unparsed("flavor", flavor.name().toLowerCase())
            );

            return Command.SINGLE_SUCCESS;
        }))
    .build();