From 56969db9d7a605aa79bec679046b6bc2de7a9d6a Mon Sep 17 00:00:00 2001
From: tpietzsch <tobias.pietzsch@gmail.com>
Date: Sun, 21 Mar 2021 00:19:02 +0100
Subject: [PATCH] Update javadoc

---
 .../java/net/imglib2/type/NativeType.java     | 51 ++++++-------------
 1 file changed, 16 insertions(+), 35 deletions(-)

diff --git a/src/main/java/net/imglib2/type/NativeType.java b/src/main/java/net/imglib2/type/NativeType.java
index b71a684fd..84da3df52 100644
--- a/src/main/java/net/imglib2/type/NativeType.java
+++ b/src/main/java/net/imglib2/type/NativeType.java
@@ -128,17 +128,16 @@ public interface NativeType< T extends NativeType< T > > extends Type< T >
 	 */
 	void updateContainer( Object c );
 
+	/**
+	 * Get the (modifiable) index into the current data array. The returned
+	 * instance will always be the same for the same Type.
+	 */
 	Index index();
 
 	/**
 	 * Set the index into the current data array.
-	 *
-	 * <p>
-	 * This is used by accessors (e.g., a {@link Cursor}) to position the
-	 * {@link NativeType} in the container.
-	 *
-	 * @param i
-	 *            the new array index
+	 * @deprecated Use {@code index().set(int)} instead. If possible, request the
+	 * {@code index()} object only once and re-use it.
 	 */
 	@Deprecated
 	default void updateIndex( final int i )
@@ -148,12 +147,8 @@ default void updateIndex( final int i )
 
 	/**
 	 * Get the current index into the current data array.
-	 *
-	 * <p>
-	 * This is used by accessors (e.g., a {@link Cursor}) to position the
-	 * {@link NativeType} in the container.
-	 *
-	 * @return the current index into the underlying data array
+	 * @deprecated Use {@code index().get()} instead. If possible, request the
+	 * {@code index()} object only once and re-use it.
 	 */
 	@Deprecated
 	default int getIndex()
@@ -163,10 +158,8 @@ default int getIndex()
 
 	/**
 	 * Increment the index into the current data array.
-	 *
-	 * <p>
-	 * This is used by accessors (e.g., a {@link Cursor}) to position the
-	 * {@link NativeType} in the container.
+	 * @deprecated Use {@code index().inc()} instead. If possible, request the
+	 * {@code index()} object only once and re-use it.
 	 */
 	@Deprecated
 	default void incIndex()
@@ -177,13 +170,8 @@ default void incIndex()
 	/**
 	 * Increases the index into the current data array by {@code increment}
 	 * steps.
-	 *
-	 * <p>
-	 * This is used by accessors (e.g., a {@link Cursor}) to position the
-	 * {@link NativeType} in the container.
-	 *
-	 * @param increment
-	 *            how many steps
+	 * @deprecated Use {@code index().inc(int)} instead. If possible, request the
+	 * {@code index()} object only once and re-use it.
 	 */
 	@Deprecated
 	default void incIndex( final int increment )
@@ -193,10 +181,8 @@ default void incIndex( final int increment )
 
 	/**
 	 * Decrement the index into the current data array.
-	 *
-	 * <p>
-	 * This is used by accessors (e.g., a {@link Cursor}) to position the
-	 * {@link NativeType} in the container.
+	 * @deprecated Use {@code index().dec()} instead. If possible, request the
+	 * {@code index()} object only once and re-use it.
 	 */
 	@Deprecated
 	default void decIndex()
@@ -207,13 +193,8 @@ default void decIndex()
 	/**
 	 * Decrease the index into the current data array by {@code decrement}
 	 * steps.
-	 *
-	 * <p>
-	 * This is used by accessors (e.g., a {@link Cursor}) to position the
-	 * {@link NativeType} in the container.
-	 *
-	 * @param decrement
-	 *            how many steps
+	 * @deprecated Use {@code index().dec(int)} instead. If possible, request the
+	 * {@code index()} object only once and re-use it.
 	 */
 	@Deprecated
 	default void decIndex( final int decrement )