docs: Move the GIOScheduler SECTION

Move it to a separate page, as there isn’t a `GIOScheduler` struct.
Ensure that all its functions/methods/types are correctly marked as
deprecated. Fix a few broken links about I/O priority which pointed to
it.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037

docs/reference/gio/gio.toml.in

@@ -55,6 +55,8 @@ content_files = [
   "migrating-gdbus.md",
   "migrating-gconf.md",
   "migrating-gnome-vfs.md",
+
+  "io-scheduler.md",
 ]
 content_images = [
   "gvfs-overview.png",

docs/reference/gio/io-scheduler.md

@@ -0,0 +1,20 @@
+Title: GIOScheduler
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2007 Andrew Walton
+
+# GIOScheduler
+
+Schedules asynchronous I/O operations. `GIOScheduler` integrates
+into the main event loop ([struct@GLib.MainLoop]) and uses threads.
+
+Deprecated: 2.36: As of GLib 2.36, `GIOScheduler` is deprecated in favor of
+[struct@GLib.ThreadPool] and [class@Gio.Task].
+
+The `GIOScheduler` API is:
+ * [type@Gio.IOSchedulerJobFunc]
+ * [func@Gio.io_scheduler_push_job]
+ * [func@Gio.io_scheduler_cancel_all_jobs]
+ * [type@Gio.IOSchedulerJob]
+ * [method@Gio.IOSchedulerJob.send_to_mainloop]
+ * [method@Gio.IOSchedulerJob.send_to_mainloop_async]
+

docs/reference/gio/meson.build

@@ -232,6 +232,7 @@ expand_content_files = [
   'dbus-utils.md',
   'error.md',
   'file-attributes.md',
+  'io-scheduler.md',
   'migrating-gconf.md',
   'migrating-gdbus.md',
   'migrating-gnome-vfs.md',

gio/gfileiostream.c

@@ -190,7 +190,8 @@ async_ready_callback_wrapper (GObject *source_object,
  * g_file_io_stream_query_info_async:
  * @stream: a #GFileIOStream.
  * @attributes: a file attribute query string.
- * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
+ * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the
+ *   request
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @callback: (scope async): a #GAsyncReadyCallback
  *   to call when the request is satisfied

gio/gfileoutputstream.c

@@ -187,7 +187,8 @@ async_ready_callback_wrapper (GObject *source_object,
  * g_file_output_stream_query_info_async:
  * @stream: a #GFileOutputStream.
  * @attributes: a file attribute query string.
- * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
+ * @io_priority: the [I/O priority](iface.AsyncResult.html#io-priority) of the
+ *   request
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
  * @user_data: the data to pass to callback function

gio/gioscheduler.c

@@ -26,18 +26,6 @@
 #include "gcancellable.h"
 #include "gtask.h"
 
-/**
- * SECTION:gioscheduler
- * @short_description: I/O Scheduler
- * @include: gio/gio.h
- * 
- * As of GLib 2.36, #GIOScheduler is deprecated in favor of
- * #GThreadPool and #GTask.
- *
- * Schedules asynchronous I/O operations. #GIOScheduler integrates 
- * into the main event loop (#GMainLoop) and uses threads.
- */
-
 struct _GIOSchedulerJob {
   GList *active_link;
   GTask *task;
@@ -110,7 +98,7 @@ io_job_thread (GTask         *task,
  * by calling g_cancellable_cancel() or by calling 
  * g_io_scheduler_cancel_all_jobs().
  *
- * Deprecated: use #GThreadPool or g_task_run_in_thread()
+ * Deprecated: 2.36: use #GThreadPool or g_task_run_in_thread()
  **/
 void
 g_io_scheduler_push_job (GIOSchedulerJobFunc  job_func,
@@ -157,7 +145,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
  * A job is cancellable if a #GCancellable was passed into
  * g_io_scheduler_push_job().
  *
- * Deprecated: You should never call this function, since you don't
+ * Deprecated: 2.36: You should never call this function, since you don't
  * know how other libraries in your program might be making use of
  * gioscheduler.
  **/
@@ -236,7 +224,7 @@ mainloop_proxy_free (MainLoopProxy *proxy)
  *
  * Returns: The return value of @func
  *
- * Deprecated: Use g_main_context_invoke().
+ * Deprecated: 2.36: Use g_main_context_invoke().
  **/
 gboolean
 g_io_scheduler_job_send_to_mainloop (GIOSchedulerJob *job,
@@ -295,7 +283,7 @@ g_io_scheduler_job_send_to_mainloop (GIOSchedulerJob *job,
  * @func is called, either by passing %NULL as @notify to 
  * g_io_scheduler_push_job() or by using refcounting for @user_data.
  *
- * Deprecated: Use g_main_context_invoke().
+ * Deprecated: 2.36: Use g_main_context_invoke().
  **/
 void
 g_io_scheduler_job_send_to_mainloop_async (GIOSchedulerJob *job,

gio/giotypes.h

@@ -110,6 +110,9 @@ typedef struct _GIOExtension                  GIOExtension;
  * GIOSchedulerJob:
  *
  * Opaque class for defining and scheduling IO jobs.
+ *
+ * Deprecated: 2.36: Use [struct@GLib.ThreadPool] or
+ *   [method@Gio.Task.run_in_thread]
  **/
 typedef struct _GIOSchedulerJob               GIOSchedulerJob;
 typedef struct _GIOStreamAdapter              GIOStreamAdapter;
@@ -357,6 +360,8 @@ typedef void (* GFileMeasureProgressCallback) (gboolean reporting,
  *
  * Returns: %TRUE if this function should be called again to
  *    complete the job, %FALSE if the job is complete (or cancelled)
+ * Deprecated: 2.36: Use [struct@GLib.ThreadPool] or
+ *   [method@Gio.Task.run_in_thread]
  **/
 typedef gboolean (*GIOSchedulerJobFunc) (GIOSchedulerJob *job,
 					 GCancellable    *cancellable,