From 90994e62fa088f858ab44aefd7de74c8c1158fb4 Mon Sep 17 00:00:00 2001 From: Mumfrey Date: Fri, 13 Jan 2017 16:54:44 +0000 Subject: [PATCH] Clarify the slice id javadoc. Are you happy now @gabizou? --- .../spongepowered/asm/mixin/injection/At.java | 4 ++- .../asm/mixin/injection/Slice.java | 28 +++++++++++++++++-- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/At.java b/src/main/java/org/spongepowered/asm/mixin/injection/At.java index 8d9f6db7..4e168ea2 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/At.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/At.java @@ -82,7 +82,9 @@ public @interface At { * this query. For other injector types it is ignored because only one slice * is supported. * - * @return + *

For more details see the {@link Slice#id}

+ * + * @return the slice identifier, or empty string to use the default slice */ public String slice() default ""; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/Slice.java b/src/main/java/org/spongepowered/asm/mixin/injection/Slice.java index 102079fc..2624ab2e 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/Slice.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/Slice.java @@ -127,8 +127,32 @@ import org.spongepowered.asm.mixin.injection.InjectionPoint.Selector; public @interface Slice { /** - * The identifier for this slice (if omitted, this slice becomes the - * default slice and applies to all undecorated {@link At} queries. + * The identifier for this slice, specified using the {@link At#slice} value + * (if omitted, this slice becomes the default slice and applies to + * all undecorated {@link At} queries). + * + *

This value can be safely ignored for injector types which only accept + * a single query (eg. {@link Redirect} and others). However since + * {@link Inject} injectors can have multiple {@link At} queries, it may be + * desirable to have multiple slices as well. When specifying multiple + * slices, each should be designed a unique id which can then be + * referenced in the corresponding At.

+ * + *

There are no specifications or restrictions for valid ids, + * however it is recommended that the id in some way describe the + * slice, thus allowing the At query to be read without necessarily + * reading the slice itself. For example, if the slice is selecting all + * instructions before the first call to some method init, + * then using an id "beforeInit makes sense. Using before, + * after and between prefixes as a loose standard is + * considered good practice.

+ * + *

This value defaults to an empty string, the empty string is used as a + * default identifier throughout the injection subsystem, and any {@link At} + * which doesn't specify a slice explicitly will use this identifer. + * Specifying id or slice for injectors which only support + * a single slice is ignored internally, so you may use this field to give a + * descriptive name to the slice if you wish.

* * @return The identifier for this slice */