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 */