@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/socket-listener.d.ts

@@ -7,19 +7,193 @@ import { SocketConnection } from "./socket-connection.js";
 import { Socket } from "./socket.js";
 import * as GObject from "../gobject/index.js";
 export declare class SocketListener extends GObject.GObject {
+    /**
+     * Creates a new #GSocketListener with no sockets to listen for.
+     * New listeners can be added with e.g. g_socket_listener_add_address()
+     * or g_socket_listener_add_inet_port().
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Blocks waiting for a client to connect to any of the sockets added
+     * to the listener. Returns a #GSocketConnection for the socket that was
+     * accepted.
+     *
+     * If `source_object` is not %NULL it will be filled out with the source
+     * object specified when the corresponding socket or address was added
+     * to the listener.
+     *
+     * If `cancellable` is not %NULL, then the operation can be cancelled by
+     * triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+     * @param sourceObject - location where #GObject pointer will be stored, or %NULL
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     accept(sourceObject?: Ref<GObject.GObject> | null, cancellable?: Cancellable | null): SocketConnection;
+    /**
+     * This is the asynchronous version of g_socket_listener_accept().
+     *
+     * When the operation is finished `callback` will be
+     * called. You can then call g_socket_listener_accept_finish()
+     * to get the result of the operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - user data for the callback
+     */
     acceptAsync(cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes an async accept operation. See g_socket_listener_accept_async()
+     * @param result - a #GAsyncResult.
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     acceptFinish(result: AsyncResult, sourceObject?: Ref<GObject.GObject> | null): SocketConnection;
+    /**
+     * Blocks waiting for a client to connect to any of the sockets added
+     * to the listener. Returns the #GSocket that was accepted.
+     *
+     * If you want to accept the high-level #GSocketConnection, not a #GSocket,
+     * which is often the case, then you should use g_socket_listener_accept()
+     * instead.
+     *
+     * If `source_object` is not %NULL it will be filled out with the source
+     * object specified when the corresponding socket or address was added
+     * to the listener.
+     *
+     * If `cancellable` is not %NULL, then the operation can be cancelled by
+     * triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+     * @param sourceObject - location where #GObject pointer will be stored, or %NULL.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     acceptSocket(sourceObject?: Ref<GObject.GObject> | null, cancellable?: Cancellable | null): Socket;
+    /**
+     * This is the asynchronous version of g_socket_listener_accept_socket().
+     *
+     * When the operation is finished `callback` will be
+     * called. You can then call g_socket_listener_accept_socket_finish()
+     * to get the result of the operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - user data for the callback
+     */
     acceptSocketAsync(cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
+     * @param result - a #GAsyncResult.
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     acceptSocketFinish(result: AsyncResult, sourceObject?: Ref<GObject.GObject> | null): Socket;
+    /**
+     * Creates a socket of type `type` and protocol @protocol, binds
+     * it to `address` and adds it to the set of sockets we're accepting
+     * sockets from.
+     *
+     * Note that adding an IPv6 address, depending on the platform,
+     * may or may not result in a listener that also accepts IPv4
+     * connections.  For more deterministic behavior, see
+     * g_socket_listener_add_inet_port().
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     *
+     * If successful and `effective_address` is non-%NULL then it will
+     * be set to the address that the binding actually occurred at.  This
+     * is helpful for determining the port number that was used for when
+     * requesting a binding to port 0 (ie: "any port").  This address, if
+     * requested, belongs to the caller and must be freed.
+     *
+     * Call g_socket_listener_close() to stop listening on @address; this will not
+     * be done automatically when you drop your final reference to @listener, as
+     * references may be held internally.
+     * @param address - a #GSocketAddress
+     * @param type - a #GSocketType
+     * @param protocol - a #GSocketProtocol
+     * @param sourceObject - Optional #GObject identifying this source
+     * @param effectiveAddress - location to store the address that was bound to, or %NULL.
+     */
     addAddress(address: SocketAddress, type: SocketType, protocol: SocketProtocol, sourceObject?: GObject.GObject | null, effectiveAddress?: Ref<SocketAddress> | null): boolean;
+    /**
+     * Listens for TCP connections on any available port number for both
+     * IPv6 and IPv4 (if each is available).
+     *
+     * This is useful if you need to have a socket for incoming connections
+     * but don't care about the specific port number.
+     *
+     * If possible, the [class@Gio.SocketListener] will listen on both IPv4 and
+     * IPv6 (listening on the same port on both). If listening on one of the socket
+     * families fails, the [class@Gio.SocketListener] will only listen on the other.
+     * If listening on both fails, an error will be returned.
+     *
+     * If you need to distinguish whether listening on IPv4 or IPv6 or both was
+     * successful, connect to [signal@Gio.SocketListener::event].
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     addAnyInetPort(sourceObject?: GObject.GObject | null): number;
+    /**
+     * Helper function for g_socket_listener_add_address() that
+     * creates a TCP/IP socket listening on IPv4 and IPv6 (if
+     * supported) on the specified port on all interfaces.
+     *
+     * If possible, the [class@Gio.SocketListener] will listen on both IPv4 and
+     * IPv6 (listening on the same port on both). If listening on one of the socket
+     * families fails, the [class@Gio.SocketListener] will only listen on the other.
+     * If listening on both fails, an error will be returned.
+     *
+     * If you need to distinguish whether listening on IPv4 or IPv6 or both was
+     * successful, connect to [signal@Gio.SocketListener::event].
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     *
+     * Call g_socket_listener_close() to stop listening on @port; this will not
+     * be done automatically when you drop your final reference to @listener, as
+     * references may be held internally.
+     * @param port - an IP port number (non-zero)
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     addInetPort(port: number, sourceObject?: GObject.GObject | null): boolean;
+    /**
+     * Adds `socket` to the set of sockets that we try to accept
+     * new clients from. The socket must be bound to a local
+     * address and listened to.
+     *
+     * For parallel calls to [class@Gio.SocketListener] methods to work, the socket
+     * must be in non-blocking mode. (See [property@Gio.Socket:blocking].)
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     *
+     * The `socket` will not be automatically closed when the `listener` is finalized
+     * unless the listener held the final reference to the socket. Before GLib 2.42,
+     * the `socket` was automatically closed on finalization of the @listener, even
+     * if references to it were held elsewhere.
+     * @param socket - a listening #GSocket
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     addSocket(socket: Socket, sourceObject?: GObject.GObject | null): boolean;
+    /**
+     * Closes all the sockets in the listener.
+     */
     close(): void;
+    /**
+     * Sets the listen backlog on the sockets in the listener. This must be called
+     * before adding any sockets, addresses or ports to the #GSocketListener (for
+     * example, by calling g_socket_listener_add_inet_port()) to be effective.
+     *
+     * See g_socket_set_listen_backlog() for details
+     * @param listenBacklog - an integer
+     */
     setBacklog(listenBacklog: number): void;
     connect(signal: "event", handler: (self: SocketListener, event: SocketListenerEvent, socket: Socket) => void, after?: boolean): number;
     connect(signal: "notify", handler: (self: SocketListener, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gio/socket-listener.js

@@ -3,6 +3,23 @@ import { NativeError, getObject } from "@gtkx/ffi";
 import { SocketConnection } from "./socket-connection.js";
 import { Socket } from "./socket.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A `GSocketListener` is an object that keeps track of a set
+ * of server sockets and helps you accept sockets from any of the
+ * socket, either sync or async.
+ *
+ * Add addresses and ports to listen on using
+ * [method@Gio.SocketListener.add_address] and
+ * [method@Gio.SocketListener.add_inet_port]. These will be listened on until
+ * [method@Gio.SocketListener.close] is called. Dropping your final reference to
+ * the `GSocketListener` will not cause [method@Gio.SocketListener.close] to be
+ * called implicitly, as some references to the `GSocketListener` may be held
+ * internally.
+ *
+ * If you want to implement a network server, also look at
+ * [class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are
+ * subclasses of `GSocketListener` that make this even easier.
+ */
 const SIGNAL_META = {
     event: {
         params: [
@@ -13,6 +30,11 @@ const SIGNAL_META = {
     },
 };
 export class SocketListener extends GObject.GObject {
+    /**
+     * Creates a new #GSocketListener with no sockets to listen for.
+     * New listeners can be added with e.g. g_socket_listener_add_address()
+     * or g_socket_listener_add_inet_port().
+     */
     constructor(...args) {
         super(...args);
     }
@@ -22,6 +44,21 @@ export class SocketListener extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * Blocks waiting for a client to connect to any of the sockets added
+     * to the listener. Returns a #GSocketConnection for the socket that was
+     * accepted.
+     *
+     * If `source_object` is not %NULL it will be filled out with the source
+     * object specified when the corresponding socket or address was added
+     * to the listener.
+     *
+     * If `cancellable` is not %NULL, then the operation can be cancelled by
+     * triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+     * @param sourceObject - location where #GObject pointer will be stored, or %NULL
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     accept(sourceObject, cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_socket_listener_accept", [
@@ -56,6 +93,16 @@ export class SocketListener extends GObject.GObject {
         }
         return getObject(ptr, SocketConnection);
     }
+    /**
+     * This is the asynchronous version of g_socket_listener_accept().
+     *
+     * When the operation is finished `callback` will be
+     * called. You can then call g_socket_listener_accept_finish()
+     * to get the result of the operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - user data for the callback
+     */
     acceptAsync(cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_socket_listener_accept_async", [
             {
@@ -79,6 +126,11 @@ export class SocketListener extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes an async accept operation. See g_socket_listener_accept_async()
+     * @param result - a #GAsyncResult.
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     acceptFinish(result, sourceObject) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_socket_listener_accept_finish", [
@@ -112,6 +164,24 @@ export class SocketListener extends GObject.GObject {
         }
         return getObject(ptr, SocketConnection);
     }
+    /**
+     * Blocks waiting for a client to connect to any of the sockets added
+     * to the listener. Returns the #GSocket that was accepted.
+     *
+     * If you want to accept the high-level #GSocketConnection, not a #GSocket,
+     * which is often the case, then you should use g_socket_listener_accept()
+     * instead.
+     *
+     * If `source_object` is not %NULL it will be filled out with the source
+     * object specified when the corresponding socket or address was added
+     * to the listener.
+     *
+     * If `cancellable` is not %NULL, then the operation can be cancelled by
+     * triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+     * @param sourceObject - location where #GObject pointer will be stored, or %NULL.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     acceptSocket(sourceObject, cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_socket_listener_accept_socket", [
@@ -146,6 +216,16 @@ export class SocketListener extends GObject.GObject {
         }
         return getObject(ptr, Socket);
     }
+    /**
+     * This is the asynchronous version of g_socket_listener_accept_socket().
+     *
+     * When the operation is finished `callback` will be
+     * called. You can then call g_socket_listener_accept_socket_finish()
+     * to get the result of the operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - user data for the callback
+     */
     acceptSocketAsync(cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_socket_listener_accept_socket_async", [
             {
@@ -169,6 +249,11 @@ export class SocketListener extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
+     * @param result - a #GAsyncResult.
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     acceptSocketFinish(result, sourceObject) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_socket_listener_accept_socket_finish", [
@@ -202,6 +287,36 @@ export class SocketListener extends GObject.GObject {
         }
         return getObject(ptr, Socket);
     }
+    /**
+     * Creates a socket of type `type` and protocol @protocol, binds
+     * it to `address` and adds it to the set of sockets we're accepting
+     * sockets from.
+     *
+     * Note that adding an IPv6 address, depending on the platform,
+     * may or may not result in a listener that also accepts IPv4
+     * connections.  For more deterministic behavior, see
+     * g_socket_listener_add_inet_port().
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     *
+     * If successful and `effective_address` is non-%NULL then it will
+     * be set to the address that the binding actually occurred at.  This
+     * is helpful for determining the port number that was used for when
+     * requesting a binding to port 0 (ie: "any port").  This address, if
+     * requested, belongs to the caller and must be freed.
+     *
+     * Call g_socket_listener_close() to stop listening on @address; this will not
+     * be done automatically when you drop your final reference to @listener, as
+     * references may be held internally.
+     * @param address - a #GSocketAddress
+     * @param type - a #GSocketType
+     * @param protocol - a #GSocketProtocol
+     * @param sourceObject - Optional #GObject identifying this source
+     * @param effectiveAddress - location to store the address that was bound to, or %NULL.
+     */
     addAddress(address, type, protocol, sourceObject, effectiveAddress) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_socket_listener_add_address", [
@@ -248,6 +363,27 @@ export class SocketListener extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Listens for TCP connections on any available port number for both
+     * IPv6 and IPv4 (if each is available).
+     *
+     * This is useful if you need to have a socket for incoming connections
+     * but don't care about the specific port number.
+     *
+     * If possible, the [class@Gio.SocketListener] will listen on both IPv4 and
+     * IPv6 (listening on the same port on both). If listening on one of the socket
+     * families fails, the [class@Gio.SocketListener] will only listen on the other.
+     * If listening on both fails, an error will be returned.
+     *
+     * If you need to distinguish whether listening on IPv4 or IPv6 or both was
+     * successful, connect to [signal@Gio.SocketListener::event].
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     addAnyInetPort(sourceObject) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_socket_listener_add_any_inet_port", [
@@ -277,6 +413,30 @@ export class SocketListener extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Helper function for g_socket_listener_add_address() that
+     * creates a TCP/IP socket listening on IPv4 and IPv6 (if
+     * supported) on the specified port on all interfaces.
+     *
+     * If possible, the [class@Gio.SocketListener] will listen on both IPv4 and
+     * IPv6 (listening on the same port on both). If listening on one of the socket
+     * families fails, the [class@Gio.SocketListener] will only listen on the other.
+     * If listening on both fails, an error will be returned.
+     *
+     * If you need to distinguish whether listening on IPv4 or IPv6 or both was
+     * successful, connect to [signal@Gio.SocketListener::event].
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     *
+     * Call g_socket_listener_close() to stop listening on @port; this will not
+     * be done automatically when you drop your final reference to @listener, as
+     * references may be held internally.
+     * @param port - an IP port number (non-zero)
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     addInetPort(port, sourceObject) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_socket_listener_add_inet_port", [
@@ -310,6 +470,26 @@ export class SocketListener extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Adds `socket` to the set of sockets that we try to accept
+     * new clients from. The socket must be bound to a local
+     * address and listened to.
+     *
+     * For parallel calls to [class@Gio.SocketListener] methods to work, the socket
+     * must be in non-blocking mode. (See [property@Gio.Socket:blocking].)
+     *
+     * `source_object` will be passed out in the various calls
+     * to accept to identify this particular source, which is
+     * useful if you're listening on multiple addresses and do
+     * different things depending on what address is connected to.
+     *
+     * The `socket` will not be automatically closed when the `listener` is finalized
+     * unless the listener held the final reference to the socket. Before GLib 2.42,
+     * the `socket` was automatically closed on finalization of the @listener, even
+     * if references to it were held elsewhere.
+     * @param socket - a listening #GSocket
+     * @param sourceObject - Optional #GObject identifying this source
+     */
     addSocket(socket, sourceObject) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_socket_listener_add_socket", [
@@ -343,6 +523,9 @@ export class SocketListener extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Closes all the sockets in the listener.
+     */
     close() {
         call("libgio-2.0.so.0", "g_socket_listener_close", [
             {
@@ -351,6 +534,14 @@ export class SocketListener extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the listen backlog on the sockets in the listener. This must be called
+     * before adding any sockets, addresses or ports to the #GSocketListener (for
+     * example, by calling g_socket_listener_add_inet_port()) to be effective.
+     *
+     * See g_socket_set_listen_backlog() for details
+     * @param listenBacklog - an integer
+     */
     setBacklog(listenBacklog) {
         call("libgio-2.0.so.0", "g_socket_listener_set_backlog", [
             {

package/dist/generated/gio/socket-service.d.ts

@@ -2,10 +2,51 @@ import { SocketConnection } from "./socket-connection.js";
 import * as GObject from "../gobject/index.js";
 import { SocketListener } from "./socket-listener.js";
 export declare class SocketService extends SocketListener {
+    /**
+     * Creates a new #GSocketService with no sockets to listen for.
+     * New listeners can be added with e.g. g_socket_listener_add_address()
+     * or g_socket_listener_add_inet_port().
+     *
+     * New services are created active, there is no need to call
+     * g_socket_service_start(), unless g_socket_service_stop() has been
+     * called before.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Check whether the service is active or not. An active
+     * service will accept new clients that connect, while
+     * a non-active service will let connecting clients queue
+     * up until the service is started.
+     */
     isActive(): boolean;
+    /**
+     * Restarts the service, i.e. start accepting connections
+     * from the added sockets when the mainloop runs. This only needs
+     * to be called after the service has been stopped from
+     * g_socket_service_stop().
+     *
+     * This call is thread-safe, so it may be called from a thread
+     * handling an incoming client request.
+     */
     start(): void;
+    /**
+     * Stops the service, i.e. stops accepting connections
+     * from the added sockets when the mainloop runs.
+     *
+     * This call is thread-safe, so it may be called from a thread
+     * handling an incoming client request.
+     *
+     * Note that this only stops accepting new connections; it does not
+     * close the listening sockets, and you can call
+     * g_socket_service_start() again later to begin listening again. To
+     * close the listening sockets, call g_socket_listener_close(). (This
+     * will happen automatically when the #GSocketService is finalized.)
+     *
+     * This must be called before calling g_socket_listener_close() as
+     * the socket service will start accepting connections immediately
+     * when a new socket is added.
+     */
     stop(): void;
     connect(signal: "incoming", handler: (self: SocketService, connection: SocketConnection, sourceObject: GObject.GObject) => boolean, after?: boolean): number;
     connect(signal: "notify", handler: (self: SocketService, pspec: GObject.ParamSpec) => void, after?: boolean): number;

package/dist/generated/gio/socket-service.js

@@ -3,6 +3,34 @@ import { getObject } from "@gtkx/ffi";
 import { SocketConnection } from "./socket-connection.js";
 import * as GObject from "../gobject/index.js";
 import { SocketListener } from "./socket-listener.js";
+/**
+ * A `GSocketService` is an object that represents a service that
+ * is provided to the network or over local sockets.  When a new
+ * connection is made to the service the [signal@Gio.SocketService::incoming]
+ * signal is emitted.
+ *
+ * A `GSocketService` is a subclass of [class@Gio.SocketListener] and you need
+ * to add the addresses you want to accept connections on with the
+ * [class@Gio.SocketListener] APIs.
+ *
+ * There are two options for implementing a network service based on
+ * `GSocketService`. The first is to create the service using
+ * [ctor@Gio.SocketService.new] and to connect to the
+ * [signal@Gio.SocketService::incoming] signal. The second is to subclass
+ * `GSocketService` and override the default signal handler implementation.
+ *
+ * In either case, the handler must immediately return, or else it
+ * will block additional incoming connections from being serviced.
+ * If you are interested in writing connection handlers that contain
+ * blocking code then see [class@Gio.ThreadedSocketService].
+ *
+ * The socket service runs on the main loop of the
+ * thread-default context (see
+ * [method@GLib.MainContext.push_thread_default]) of the thread it is
+ * created in, and is not threadsafe in general. However, the calls to start and
+ * stop the service are thread-safe so these can be used from threads that
+ * handle incoming clients.
+ */
 const SIGNAL_META = {
     incoming: {
         params: [
@@ -19,6 +47,15 @@ const SIGNAL_META = {
     },
 };
 export class SocketService extends SocketListener {
+    /**
+     * Creates a new #GSocketService with no sockets to listen for.
+     * New listeners can be added with e.g. g_socket_listener_add_address()
+     * or g_socket_listener_add_inet_port().
+     *
+     * New services are created active, there is no need to call
+     * g_socket_service_start(), unless g_socket_service_stop() has been
+     * called before.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -28,6 +65,12 @@ export class SocketService extends SocketListener {
             borrowed: false,
         });
     }
+    /**
+     * Check whether the service is active or not. An active
+     * service will accept new clients that connect, while
+     * a non-active service will let connecting clients queue
+     * up until the service is started.
+     */
     isActive() {
         return call("libgio-2.0.so.0", "g_socket_service_is_active", [
             {
@@ -36,6 +79,15 @@ export class SocketService extends SocketListener {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Restarts the service, i.e. start accepting connections
+     * from the added sockets when the mainloop runs. This only needs
+     * to be called after the service has been stopped from
+     * g_socket_service_stop().
+     *
+     * This call is thread-safe, so it may be called from a thread
+     * handling an incoming client request.
+     */
     start() {
         call("libgio-2.0.so.0", "g_socket_service_start", [
             {
@@ -44,6 +96,23 @@ export class SocketService extends SocketListener {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Stops the service, i.e. stops accepting connections
+     * from the added sockets when the mainloop runs.
+     *
+     * This call is thread-safe, so it may be called from a thread
+     * handling an incoming client request.
+     *
+     * Note that this only stops accepting new connections; it does not
+     * close the listening sockets, and you can call
+     * g_socket_service_start() again later to begin listening again. To
+     * close the listening sockets, call g_socket_listener_close(). (This
+     * will happen automatically when the #GSocketService is finalized.)
+     *
+     * This must be called before calling g_socket_listener_close() as
+     * the socket service will start accepting connections immediately
+     * when a new socket is added.
+     */
     stop() {
         call("libgio-2.0.so.0", "g_socket_service_stop", [
             {