Heavy work on improving category documentation.

Still more to go!

Reference Issue #9440.

include/SDL3/SDL_clipboard.h

@@ -26,6 +26,52 @@
  * from other processes and publishing information of its own.
  *
  * This is not just text! SDL apps can access and publish data by mimetype.
+ *
+ * ## Basic use (text)
+ *
+ * Obtaining and publishing simple text to the system clipboard is as easy
+ * as calling SDL_GetClipboardText() and SDL_SetClipboardText(),
+ * respectively. These deal with C strings in UTF-8 encoding. Data
+ * transmission and encoding conversion is completely managed by SDL.
+ *
+ * ## Clipboard callbacks (data other than text)
+ *
+ * Things get more complicated when the clipboard contains something other
+ * than text. Not only can the system clipboard contain data of any type,
+ * in some cases it can contain the same data in different formats! For
+ * example, an image painting app might let the user copy a graphic to the
+ * clipboard, and offers it in .BMP, .JPG, or .PNG format for other apps to
+ * consume.
+ *
+ * Obtaining clipboard data ("pasting") like this is a matter of calling
+ * SDL_GetClipboardData() and telling it the mimetype of the data you want.
+ * But how does one know if that format is available? SDL_HasClipboardData()
+ * can report if a specific mimetype is offered, and
+ * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes
+ * available, so the app can decide what to do with the data and what formats
+ * it can support.
+ *
+ * Setting the clipboard ("copying") to arbitrary data is done with
+ * SDL_SetClipboardData. The app does not provide the data in this call, but
+ * rather the mimetypes it is willing to provide and a callback function.
+ * During the callback, the app will generate the data. This allows massive
+ * data sets to be provided to the clipboard, without any data being copied
+ * before it is explicitly requested. More specifically, it allows an app
+ * to offer data in multiple formats without providing a copy of all of
+ * them upfront. If the app has an image that it could provide in PNG or JPG
+ * format, it doesn't have to encode it to either of those unless and until
+ * something tries to paste it.
+ *
+ * ## Primary Selection
+ *
+ * The X11 and Wayland video targets have a concept of the "primary selection"
+ * in addition to the usual clipboard. This is generally highlighted (but not
+ * explicitly copied) text from various apps. SDL offers APIs for this through
+ * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText().
+ * SDL offers these APIs on platforms without this concept, too, but only so
+ * far that it will keep a copy of a string that the app sets for later
+ * retrieval; the operating system will not ever attempt to change the
+ * string externally if it doesn't support a primary selection.
  */
 
 #ifndef SDL_clipboard_h_
@@ -181,13 +227,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
  * Offer clipboard data to the OS.
  *
  * Tell the operating system that the application is offering clipboard data
- * for each of the proivded mime-types. Once another application requests the
- * data the callback function will be called allowing it to generate and
+ * for each of the provided mime-types. Once another application requests the
+ * data the callback function will be called, allowing it to generate and
  * respond with the data for the requested mime-type.
  *
  * The size of text data does not include any terminator, and the text does
  * not need to be null terminated (e.g. you can directly copy a portion of a
- * document)
+ * document).
  *
  * \param callback a function pointer to the function that provides the
  *                 clipboard data.