[wpiutil] Add WPI_String usage documentation (NFC) (#8675)

The description is adapted from the PR description in #6299.

wpiutil/src/main/native/include/wpi/util/string.h

@@ -8,6 +8,34 @@
 
 /**
  * A const UTF8 string.
+ *
+ * Notes on usage:
+ *   1. WPILib will not have any APIs that manipulate an externally allocated
+ *      string.
+ *   2. If a WPILib API takes a `const WPI_String*`, that string is an input.
+ *      WPILib will not manipulate or attempt to free that string. It is up to
+ *      the caller to manage the memory- WPILib will never hold onto that memory
+ *      longer than the call.
+ *   3. If a WPILib API takes a `WPI_String*`, that string is an output. WPILib
+ *      will allocate that string with WPI_AllocateString(), fill in the string,
+ *      and return to the caller. When the caller is done with the string, they
+ *      must free it with WPI_FreeString().
+ *   4. If an input struct containing a WPI_String, or an input array of
+ *      [WPI_String](@ref WPI_String)s is passed to WPILib, the individual
+ *      strings will not be manipulated or freed by WPILib, and the caller owns
+ *      and should free that memory.
+ *   5. If an output struct contains a WPI_String member, that member is
+ *      considered read only, and should not be explicitly freed individually.
+ *      The caller should call the free function for that struct.
+ *   6. If an array of [WPI_String](@ref WPI_String)s is returned, each
+ *      individual string is considered read only, and should not be explicitly
+ *      freed individually. The caller should call the free function for that
+ *      array.
+ *   7. Callbacks also follow these rules. The most common situation is a
+ *      callback either getting passed a `const WPI_String*` or a struct
+ *      containing a WPI_String. In both of these cases, the callback target
+ *      should consider these strings read only, and not attempt to free them or
+ *      manipulate them.
  */
 struct WPI_String {
   /** Contents. */