docs: Move the gtls SECTION

Move it to a separate Markdown page.

Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>

Helps: #3037

docs/reference/gio/gio.toml.in

@@ -42,6 +42,7 @@ urlmap_file = "urlmap.js"
 content_files = [
   "overview.md",
   "file-attributes.md",
+  "tls-overview.md",
 
   "migrating-gdbus.md",
   "migrating-gconf.md",

docs/reference/gio/meson.build

@@ -230,6 +230,7 @@ expand_content_files = [
   'migrating-gdbus.md',
   'migrating-gnome-vfs.md',
   'overview.md',
+  'tls-overview.md',
 ]
 
 gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)

docs/reference/gio/tls-overview.md

@@ -0,0 +1,37 @@
+Title: TLS Overview
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2010 Dan Winship
+SPDX-FileCopyrightText: 2015 Collabora, Ltd.
+
+# TLS Overview
+
+[class@Gio.TlsConnection] and related classes provide TLS (Transport Layer
+Security, previously known as SSL, Secure Sockets Layer) support for GIO-based
+network streams.
+
+[iface@Gio.DtlsConnection] and related classes provide DTLS (Datagram TLS)
+support for GIO-based network sockets, using the [iface@Gio.DatagramBased]
+interface. The TLS and DTLS APIs are almost identical, except TLS is
+stream-based and DTLS is datagram-based. They share certificate and backend
+infrastructure.
+
+In the simplest case, for a client TLS connection, you can just set the
+[property@Gio.SocketClient:tls] flag on a [class@Gio.SocketClient], and then any
+connections created by that client will have TLS negotiated automatically, using
+appropriate default settings, and rejecting any invalid or self-signed
+certificates (unless you change that default by setting the
+[property@Gio.SocketClient:tls-validation-flags] property). The returned object
+will be a [class@Gio.TcpWrapperConnection], which wraps the underlying
+[iface@Gio.TlsClientConnection].
+
+For greater control, you can create your own [iface@Gio.TlsClientConnection],
+wrapping a [class@Gio.SocketConnection] (or an arbitrary [class@Gio.IOStream]
+with pollable input and output streams) and then connect to its signals,
+such as [signal@Gio.TlsConnection::accept-certificate], before starting the
+handshake.
+
+Server-side TLS is similar, using [iface@Gio.TlsServerConnection]. At the
+moment, there is no support for automatically wrapping server-side
+connections in the way [class@Gio.SocketClient] does for client-side
+connections.
+

gio/gtlsbackend.c

@@ -28,53 +28,6 @@
 #include "gioenumtypes.h"
 #include "giomodule-priv.h"
 
-/**
- * SECTION:gtls
- * @title: TLS Overview
- * @short_description: TLS (aka SSL) support for GSocketConnection
- * @include: gio/gio.h
- *
- * #GTlsConnection and related classes provide TLS (Transport Layer
- * Security, previously known as SSL, Secure Sockets Layer) support for
- * gio-based network streams.
- *
- * #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for
- * GIO-based network sockets, using the #GDatagramBased interface. The TLS and
- * DTLS APIs are almost identical, except TLS is stream-based and DTLS is
- * datagram-based. They share certificate and backend infrastructure.
- *
- * In the simplest case, for a client TLS connection, you can just set the
- * #GSocketClient:tls flag on a #GSocketClient, and then any
- * connections created by that client will have TLS negotiated
- * automatically, using appropriate default settings, and rejecting
- * any invalid or self-signed certificates (unless you change that
- * default by setting the #GSocketClient:tls-validation-flags
- * property). The returned object will be a #GTcpWrapperConnection,
- * which wraps the underlying #GTlsClientConnection.
- *
- * For greater control, you can create your own #GTlsClientConnection,
- * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
- * pollable input and output streams) and then connect to its signals,
- * such as #GTlsConnection::accept-certificate, before starting the
- * handshake.
- *
- * Server-side TLS is similar, using #GTlsServerConnection. At the
- * moment, there is no support for automatically wrapping server-side
- * connections in the way #GSocketClient does for client-side
- * connections.
- */
-
-/**
- * SECTION:gtlsbackend
- * @title: GTlsBackend
- * @short_description: TLS backend implementation
- * @include: gio/gio.h
- *
- * TLS (Transport Layer Security, aka SSL) and DTLS backend.
- *
- * Since: 2.28
- */
-
 /**
  * GTlsBackend:
  *