docs: Discourage use of Buffer's pos_of, index_of (#2225)

These methods assume that the backing store of any buffer / area is linearly indexable. There are other ways that we might want to experiment in the future with how to store the values (trees, 2D allocated areas that are non-contiguous etc.). The index <-> pos conversion there isn't particularly useful. This should be an internal implementation detail of the buffer, rather than something that we expose, but we're not deprecating this for now at least.

ratatui-core/src/buffer/buffer.rs

@@ -216,6 +216,9 @@ impl Buffer {
     ///
     /// Global coordinates are offset by the Buffer's area offset (`x`/`y`).
     ///
+    /// Usage discouraged, as it exposes `self.content` as a linearly indexable array, which limits
+    /// potential future abstractions. See <https://github.com/ratatui/ratatui/issues/1122>.
+    ///
     /// # Examples
     ///
     /// ```
@@ -269,10 +272,13 @@ impl Buffer {
         Some(y * width + x)
     }
 
-    /// Returns the (global) coordinates of a cell given its index
+    /// Returns the (global) coordinates of a cell given its index.
     ///
     /// Global coordinates are offset by the Buffer's area offset (`x`/`y`).
     ///
+    /// Usage discouraged, as it exposes `self.content` as a linearly indexable array, which limits
+    /// potential future abstractions. See <https://github.com/ratatui/ratatui/issues/1122>.
+    ///
     /// # Examples
     ///
     /// ```