xeme/xeme

Clean up a ton of stuff in the docs

5 months ago, Gary Kramlich
1e81da6ffa54
Parents bf5e38212661
Children 3e71e31d1065
Clean up a ton of stuff in the docs

This is mostly just adding missing documentation but we also changed the since
tags to just be major.minor by removing the micro which shouldn't be a part of
the API versioning.

Testing Done:
Built the docs and verified them locally.

Reviewed at https://reviews.imfreedom.org/r/2905/
--- a/xeme/xemeaddress.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeaddress.h Mon Jan 01 00:40:14 2024 -0600
@@ -40,7 +40,7 @@
*
* Returns: %TRUE if @address was valid, otherwise %FALSE.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
gboolean xeme_address_parse(const char *address, char **bare_jid, char **local, char **domain, char **resource);
--- a/xeme/xemeconnection.c Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeconnection.c Mon Jan 01 00:40:14 2024 -0600
@@ -317,7 +317,7 @@
*
* The "Jabber ID" which this connection originates from.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_JID] = g_param_spec_string(
"jid", "jid",
@@ -339,7 +339,7 @@
* Resources are mostly deprecated, but this property can be modify to set
* it to whatever you like.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_RESOURCE] = g_param_spec_string(
"resource", "resource",
@@ -355,7 +355,7 @@
* If this is set, it will be the only connection attempt made. See
* [method@Connection.connect_async] for more information.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_SERVER] = g_param_spec_string(
"server", "server",
@@ -370,7 +370,7 @@
*
* This will only be used if [property@Connection:server] is not %NULL.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_PORT] = g_param_spec_uint(
"port", "port",
@@ -386,7 +386,7 @@
* This determines whether or not a TLS connection is attempted at all or
* if STARTTLS is used to upgrade a clear connection.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_TLS_MODE] = g_param_spec_enum(
"tls-mode", "tls-mode",
--- a/xeme/xemeconnection.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeconnection.h Mon Jan 01 00:40:14 2024 -0600
@@ -29,6 +29,18 @@
G_BEGIN_DECLS
+/**
+ * XemeConnection:
+ *
+ * A client to server connection.
+ *
+ * This object manages the connection to the server, handles feature
+ * negotiation including STARTTLS, stream restarts, and other things that are
+ * part of XMPP Core.
+ *
+ * Since: 0.1
+ */
+
#define XEME_TYPE_CONNECTION (xeme_connection_get_type())
XEME_AVAILABLE_IN_0_1
@@ -44,7 +56,7 @@
*
* An enumeration representing which mode of TLS to use.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
typedef enum {
XEME_TLS_MODE_DIRECT_TLS,
@@ -64,7 +76,7 @@
*
* Returns: (transfer full): The new instance.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
XemeConnection *xeme_connection_new(const char *jid);
@@ -78,7 +90,7 @@
*
* Returns: The bare jid.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
const char *xeme_connection_get_jid(XemeConnection *connection);
@@ -93,7 +105,7 @@
*
* Returns: (transfer none) (nullable): The resource if set otherwise %NULL.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_connection_get_resource(XemeConnection *connection);
@@ -105,7 +117,7 @@
*
* Sets the resource of @connection to @resource.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_connection_set_resource(XemeConnection *connection, const char *resource);
@@ -119,7 +131,7 @@
* Returns: (transfer none) (nullable): The canncellable if one is set,
* otherwise %NULL.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
GCancellable *xeme_connection_get_cancellable(XemeConnection *connection);
@@ -134,7 +146,7 @@
*
* Returns: (nullable): The explicit server to connect to or %NULL.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_connection_get_server(XemeConnection *connection);
@@ -148,7 +160,7 @@
*
* Passing %NULL for @server will unset any previous value.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_connection_set_server(XemeConnection *connection, const char *server);
@@ -161,7 +173,7 @@
*
* Returns: The port to use.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
guint16 xeme_connection_get_port(XemeConnection *connection);
@@ -173,7 +185,7 @@
*
* Sets the port to use for @connection to @port.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_connection_set_port(XemeConnection *connection, guint16 port);
@@ -186,7 +198,7 @@
*
* Returns: The TLS mode to use.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
XemeTlsMode xeme_connection_get_tls_mode(XemeConnection *connection);
@@ -198,7 +210,7 @@
*
* Sets the [enum@TlsMode] of @connection to @tls_mode.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_connection_set_tls_mode(XemeConnection *connection, XemeTlsMode tls_mode);
@@ -237,7 +249,7 @@
* will attempt to upgrade to TLS during the connection process. If this fails,
* the connection will be terminated.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_connection_connect_async(XemeConnection *connection, XemeInputStream *input, GProxyResolver *resolver, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer data);
@@ -257,7 +269,7 @@
* Returns: (transfer full): A new [class@OutputStream] or %NULL if the
* connection failed.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
XemeOutputStream *xeme_connection_connect_finish(XemeConnection *connection, GAsyncResult *result, GError **error);
@@ -271,7 +283,7 @@
*
* Returns: %TRUE if sucessfull, otherwise %FALSE with @error possibly set.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
gboolean xeme_connection_close(XemeConnection *connection, GError **error);
--- a/xeme/xemeconstants.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeconstants.h Mon Jan 01 00:40:14 2024 -0600
@@ -25,7 +25,7 @@
*
* A constant representing the default clear text port.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_PORT_CLEAR (5222) XEME_AVAILABLE_MACRO_IN_0_1
@@ -34,7 +34,7 @@
*
* A constant representing the default TLS port.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_PORT_TLS (5223) XEME_AVAILABLE_MACRO_IN_0_1
@@ -44,7 +44,7 @@
* A constant representing the xmpp-client service DNS record for clear text
* connections.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_SERVICE_XMPP_CLIENT ("xmpp-client") XEME_AVAILABLE_MACRO_IN_0_1
@@ -54,7 +54,7 @@
* A constant representing the xmpps-client service DNS record for TLS
* connections.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_SERVICE_XMPPS_CLIENT ("xmpps-client") XEME_AVAILABLE_MACRO_IN_0_1
--- a/xeme/xemecore.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemecore.h Mon Jan 01 00:40:14 2024 -0600
@@ -20,6 +20,13 @@
#include <glib.h>
+/**
+ * XEME_DOMAIN:
+ *
+ * A constant to represent an error from Xeme.
+ *
+ * Since: 0.1
+ */
#define XEME_DOMAIN (g_quark_from_static_string("xeme")) XEME_AVAILABLE_MACRO_IN_0_1
#endif /* XEME_CORE_H */
--- a/xeme/xemeextension.c Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeextension.c Mon Jan 01 00:40:14 2024 -0600
@@ -142,7 +142,7 @@
*
* The name of the element that's being extended.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_ELEMENT] = g_param_spec_string(
"element", "element",
@@ -155,7 +155,7 @@
*
* The namespace of the extension.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_NAMESPACE] = g_param_spec_string(
"namespace", "namespace",
--- a/xeme/xemeextension.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeextension.h Mon Jan 01 00:40:14 2024 -0600
@@ -30,10 +30,10 @@
/**
* XemeExtension:
*
- * The base class for representing
+ * The base class for
* [extension elements](https://datatracker.ietf.org/doc/html/rfc6120#section-8.4).
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_TYPE_EXTENSION (xeme_extension_get_type())
@@ -60,7 +60,7 @@
*
* Gets the name of the element from @extension.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_extension_get_element(XemeExtension *extension);
@@ -71,7 +71,7 @@
*
* Gets the namespace from @extension.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_extension_get_namespace(XemeExtension *extension);
@@ -87,7 +87,7 @@
* [method@GLib.MarkupParseContext.push] with its own parser to parse the data
* and set @extension appropriately.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_extension_parse(XemeExtension *extension, GMarkupParseContext *context);
@@ -102,7 +102,7 @@
*
* Returns: (transfer full): The XML data as a string for @extension.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
char *xeme_extension_serialize(XemeExtension *extension);
--- a/xeme/xemeinputstream.c Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeinputstream.c Mon Jan 01 00:40:14 2024 -0600
@@ -240,7 +240,7 @@
*
* Emitted when the input stream is closed.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
signals[SIG_CLOSED] = g_signal_new_class_handler(
"closed",
--- a/xeme/xemeinputstream.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeinputstream.h Mon Jan 01 00:40:14 2024 -0600
@@ -31,6 +31,14 @@
#define XEME_TYPE_INPUT_STREAM (xeme_input_stream_get_type())
+/**
+ * XemeInputStream:
+ *
+ * An object that handles the incoming stream from a remote connection.
+ *
+ * Since: 0.1
+ */
+
XEME_AVAILABLE_IN_0_1
G_DECLARE_DERIVABLE_TYPE(XemeInputStream, xeme_input_stream, XEME, INPUT_STREAM, XemeStream)
@@ -49,7 +57,7 @@
*
* Returns: (transfer full): The new instance.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
XemeInputStream *xeme_input_stream_new(void);
@@ -71,7 +79,7 @@
*
* Returns: %TRUE on success, otherwise %FALSE with @error set.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
gboolean xeme_input_stream_start(XemeInputStream *stream, GInputStream *input, GError **error);
--- a/xeme/xememessage.c Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xememessage.c Mon Jan 01 00:40:14 2024 -0600
@@ -239,7 +239,7 @@
*
* The thread identifier for this message.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_THREAD] = g_param_spec_string(
"thread", "thread",
@@ -252,7 +252,7 @@
*
* The thread parent identifier for this message.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_THREAD_PARENT] = g_param_spec_string(
"thread-parent", "thread-parent",
--- a/xeme/xememessage.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xememessage.h Mon Jan 01 00:40:14 2024 -0600
@@ -28,6 +28,14 @@
#define XEME_TYPE_MESSAGE (xeme_message_get_type())
+/**
+ * XemeMessage:
+ *
+ * An XMPP message stanza.
+ *
+ * Since: 0.1
+ */
+
XEME_AVAILABLE_IN_0_1
G_DECLARE_FINAL_TYPE(XemeMessage, xeme_message, XEME, MESSAGE, XemeStanza)
@@ -38,7 +46,7 @@
*
* returns: (transfer full): The new message.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
XemeStanza *xeme_message_new(void);
@@ -51,7 +59,7 @@
*
* Returns: (transfer none) (nullable): The thread id.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_message_get_thread(XemeMessage *message);
@@ -63,7 +71,7 @@
*
* Sets the thread identifier of @message.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_message_set_thread(XemeMessage *message, const char *thread);
@@ -76,7 +84,7 @@
*
* Returns: (transfer none) (nullable): The thread id.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_message_get_thread_parent(XemeMessage *message);
@@ -88,7 +96,7 @@
*
* Sets the thread parent identifier of @message.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_message_set_thread_parent(XemeMessage *message, const char *thread_parent);
@@ -102,7 +110,7 @@
* Add @content as a subject to @message. If a subject already exists with
* @language, it will be replaced by the new @content.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_message_add_subject(XemeMessage *message, const char *language, const char *content);
@@ -116,7 +124,7 @@
* Add @content as a body to @message. If a body already exists with @language,
* it will be replaced by the new @content.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_message_add_body(XemeMessage *message, const char *language, const char *content);
--- a/xeme/xemeoutputstream.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeoutputstream.h Mon Jan 01 00:40:14 2024 -0600
@@ -30,6 +30,14 @@
#define XEME_TYPE_OUTPUT_STREAM (xeme_output_stream_get_type())
+/**
+ * XemeOutputStream:
+ *
+ * A stream to send XMPP stanzas to a remote connection.
+ *
+ * Since: 0.1
+ */
+
XEME_AVAILABLE_IN_0_1
G_DECLARE_FINAL_TYPE(XemeOutputStream, xeme_output_stream, XEME, OUTPUT_STREAM, XemeStream)
@@ -42,7 +50,7 @@
*
* Returns: (transfer full): The new instance.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
XemeOutputStream *xeme_output_stream_new(const char *to, const char *from, GCancellable *cancellable);
@@ -64,7 +72,7 @@
*
* Returns: %TRUE on success, otherwise %FALSE with @error set.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
gboolean xeme_output_stream_start(XemeOutputStream *stream, GOutputStream *output, GError **error);
@@ -83,7 +91,7 @@
*
* Returns: %TRUE on success, otherwise %FALSE with @error set.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
gboolean xeme_output_stream_restart(XemeOutputStream *stream, GError **error);
@@ -98,7 +106,7 @@
*
* Returns: %TRUE on success, otherwise %FALSE with @error possibly set.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
gboolean xeme_output_stream_stop(XemeOutputStream *stream, GError **error);
--- a/xeme/xemestanza.c Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemestanza.c Mon Jan 01 00:40:14 2024 -0600
@@ -129,7 +129,7 @@
*
* The content type of this stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_CONTENT_TYPE] = g_param_spec_string(
"content-type", "content-type",
@@ -142,7 +142,7 @@
*
* The sender of this stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_FROM] = g_param_spec_string(
"from", "from",
@@ -155,7 +155,7 @@
*
* The identifier of this stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_ID] = g_param_spec_string(
"id", "id",
@@ -168,7 +168,7 @@
*
* The recipient of this stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_TO] = g_param_spec_string(
"to", "to",
@@ -181,7 +181,7 @@
*
* The XML Lang value for this stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_XML_LANG] = g_param_spec_string(
"xml-lang", "xml-lang",
--- a/xeme/xemestanza.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemestanza.h Mon Jan 01 00:40:14 2024 -0600
@@ -27,6 +27,14 @@
#define XEME_TYPE_STANZA (xeme_stanza_get_type())
+/**
+ * XemeStanza:
+ *
+ * The base class for XMPP stanzas including Message, IQ, and Presence.
+ *
+ * Since: 0.1
+ */
+
XEME_AVAILABLE_IN_0_1
G_DECLARE_DERIVABLE_TYPE(XemeStanza, xeme_stanza, XEME, STANZA, GObject)
@@ -49,7 +57,7 @@
*
* Returns: (nullable): The content type of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stanza_get_content_type(XemeStanza *stanza);
@@ -61,7 +69,7 @@
*
* Sets the content type of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stanza_set_content_type(XemeStanza *stanza, const char *content_type);
@@ -74,7 +82,7 @@
*
* Returns: (nullable): The sender of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stanza_get_from(XemeStanza *stanza);
@@ -86,7 +94,7 @@
*
* Sets the sender of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stanza_set_from(XemeStanza *stanza, const char *from);
@@ -99,7 +107,7 @@
*
* Returns: (nullable): The identifier of the stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stanza_get_id(XemeStanza *stanza);
@@ -111,7 +119,7 @@
*
* Sets the identifier of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stanza_set_id(XemeStanza *stanza, const char *id);
@@ -124,7 +132,7 @@
*
* Returns: (nullable): The recipient of this stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stanza_get_to(XemeStanza *stanza);
@@ -136,7 +144,7 @@
*
* Sets the recipient of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stanza_set_to(XemeStanza *stanza, const char *to);
@@ -149,7 +157,7 @@
*
* Returns: (nullable): The XML lang of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stanza_get_xml_lang(XemeStanza *stanza);
@@ -161,7 +169,7 @@
*
* Sets the XML Lang of @stanza.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stanza_set_xml_lang(XemeStanza *stanza, const char *xml_lang);
@@ -177,7 +185,7 @@
* Returns: (transfer full) (nullable): The marshaled stanza as a string or
* %NULL with error set on failure.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
char *xeme_stanza_marshal(XemeStanza *stanza, GError **error);
@@ -195,7 +203,7 @@
*
* Returns: (transfer full) (nullable): The attributes marshaled as a string.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
char *xeme_stanza_marshal_attributes(XemeStanza *stanza);
--- a/xeme/xemestream.c Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemestream.c Mon Jan 01 00:40:14 2024 -0600
@@ -161,7 +161,7 @@
*
* The cancellable for this stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_CANCELLABLE] = g_param_spec_object(
"cancellable", "cancellable",
@@ -174,7 +174,7 @@
*
* The initiator of the stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_ID] = g_param_spec_string(
"id", "id",
@@ -187,7 +187,7 @@
*
* The bare jid of the remote side of this stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_TO] = g_param_spec_string(
"to", "to",
@@ -200,7 +200,7 @@
*
* The bare jid of the local side of this stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_FROM] = g_param_spec_string(
"from", "from",
@@ -213,7 +213,7 @@
*
* The language for this stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_LANGUAGE] = g_param_spec_string(
"language", "language",
@@ -226,7 +226,7 @@
*
* The XMPP version for this stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
properties[PROP_VERSION] = g_param_spec_string(
"version", "version",
--- a/xeme/xemestream.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemestream.h Mon Jan 01 00:40:14 2024 -0600
@@ -27,11 +27,52 @@
G_BEGIN_DECLS
+/**
+ * XEME_STREAM_PI:
+ *
+ * A basic UTF-8 XML Processing Instruction.
+ *
+ * Since: 0.1
+ */
#define XEME_STREAM_PI "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" XEME_AVAILABLE_MACRO_IN_0_1
+
+/**
+ * XEME_STREAM_VERSION:
+ *
+ * The version of the XMPP stream.
+ *
+ * Since: 0.1
+ */
#define XEME_STREAM_VERSION "1.0" XEME_AVAILABLE_MACRO_IN_0_1
+
+/**
+ * XEME_STREAM_XMLNS:
+ *
+ * The value for the default namespace of the XML document.
+ *
+ * Since: 0.1
+ */
#define XEME_STREAM_XMLNS "jabber:client" XEME_AVAILABLE_MACRO_IN_0_1
+
+/**
+ * XEME_STREAM_XMLNS_STREAM:
+ *
+ * The value for the stream namespace of the XML document.
+ *
+ * Since: 0.1
+ */
#define XEME_STREAM_XMLNS_STREAM "http://etherx.jabber.org/streams" XEME_AVAILABLE_MACRO_IN_0_1
+/**
+ * XemeStream:
+ *
+ * A base class for representing XMPP streams.
+ *
+ * This mostly just contains common properties that are needed by
+ * [class@InputStream] and [class@OutputStream].
+ *
+ * Since: 0.1
+ */
#define XEME_TYPE_STREAM (xeme_stream_get_type())
XEME_AVAILABLE_IN_0_1
@@ -53,7 +94,7 @@
*
* Returns: (transfer none): The cancellable for @stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
GCancellable *xeme_stream_get_cancellable(XemeStream *stream);
@@ -66,7 +107,7 @@
*
* Returns: The id.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stream_get_id(XemeStream *stream);
@@ -78,7 +119,7 @@
*
* Sets the identifier for @stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stream_set_id(XemeStream *stream, const char *id);
@@ -91,7 +132,7 @@
*
* Returns: The bare jid of the remote side.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stream_get_to(XemeStream *stream);
@@ -103,7 +144,7 @@
*
* Sets the bare jid for the remote side of @stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stream_set_to(XemeStream *stream, const char *to);
@@ -116,7 +157,7 @@
*
* Returns: The bare jid of the local side.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stream_get_from(XemeStream *stream);
@@ -128,7 +169,7 @@
*
* Sets the bare jid for the local side of @stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stream_set_from(XemeStream *stream, const char *from);
@@ -141,7 +182,7 @@
*
* Returns: The language that @stream is using.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stream_get_language(XemeStream *stream);
@@ -155,7 +196,7 @@
* before the stream is started but will be populated if the remote side
* sends it.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stream_set_language(XemeStream *stream, const char *language);
@@ -168,7 +209,7 @@
*
* Returns: The version of @stream or %NULL if unset.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
const char *xeme_stream_get_version(XemeStream *stream);
@@ -180,7 +221,7 @@
*
* Sets the XMPP version for @stream.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_0_1
void xeme_stream_set_version(XemeStream *stream, const char *version);
--- a/xeme/xemestring.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemestring.h Mon Jan 01 00:40:14 2024 -0600
@@ -30,7 +30,7 @@
*
* Returns: %TRUE if @str is empty, otherwise %FALSE.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_STATIC_INLINE_IN_0_1
static inline gboolean
@@ -47,7 +47,7 @@
*
* Returns: %TRUE if the strings are equal or %FALSE.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_STATIC_INLINE_IN_0_1
static inline gboolean
--- a/xeme/xemeversion.h Sun Dec 31 23:02:19 2023 -0600
+++ b/xeme/xemeversion.h Mon Jan 01 00:40:14 2024 -0600
@@ -45,6 +45,54 @@
#define _XEME_EXTERN _XEME_API extern
+/**
+ * XEME_DEPRECATED:
+ *
+ * Used to mark a symbol as deprecated.
+ *
+ * Since: 0.1
+ */
+
+/**
+ * XEME_DEPRECATED_FOR:
+ * @f: The new symbol to use.
+ *
+ * Marks a symbol as deprecated and causes a warning to be displayed that says
+ * that @f replaces the deprecated symbol.
+ *
+ * Since: 0.1
+ */
+
+/**
+ * XEME_UNAVAILABLE:
+ * @maj: The major version when this symbol was introduced.
+ * @min: The minor version when this symbol was introduced.
+ *
+ * Marks a symbol as unavailable before version @maj.@min.
+ *
+ * Since: 0.1
+ */
+
+/**
+ * XEME_UNAVAILABLE_STATIC_INLINE:
+ * @maj: The major version when this static inline was introduced.
+ * @min: The minor version when this static inline was introduced.
+ *
+ * Marks a static inline function as unavailable before version @maj.@min.
+ *
+ * Since: 0.1
+ */
+
+/**
+ * XEME_UNAVAILABLE_TYPE:
+ * @maj: The major version when this type was introduced.
+ * @min: The minor version when this type was introduced.
+ *
+ * Marks a type as unavailable before version @maj.@min.
+ *
+ * Since: 0.1
+ */
+
#ifdef XEME_DISABLE_DEPRECATION_WARNINGS
#define XEME_DEPRECATED _XEME_EXTERN
#define XEME_DEPRECATED_FOR(f) _XEME_EXTERN
@@ -65,14 +113,21 @@
* A macro that evaluates to the current stable version of xeme, in a format
* that can be used by the C pre-processor.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_VERSION_CUR_STABLE \
(G_ENCODE_VERSION(XEME_MAJOR_VERSION, XEME_MINOR_VERSION))
-/* If the package sets XEME_VERSION_MIN_REQUIRED to some future
- * XEME_VERSION_X_Y value that we don't know about, it will compare as 0 in
- * preprocessor tests.
+/**
+ * XEME_VERSION_MIN_REQUIRED:
+ *
+ * The minimum required version of Xeme.
+ *
+ * Users should set this to help identify which symbols are available during
+ * compilation.
+ *
+ * If [const@VERSION_MIN_REQUIRED] is set to some future `XEME_VERSION_X_Y`
+ * value that isn't known, it will compare as 0 in preprocessor tests.
*/
#ifndef XEME_VERSION_MIN_REQUIRED
#define XEME_VERSION_MIN_REQUIRED (XEME_VERSION_CUR_STABLE)
@@ -106,7 +161,7 @@
* A macro that evaluates to the 0.1 version of xeme, in a format that can be
* used by the C pre-processor.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_VERSION_0_1 (G_ENCODE_VERSION(0, 1))
@@ -138,7 +193,7 @@
* Returns: %TRUE if the version is the same or newer than the passed-in
* version.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
#define XEME_CHECK_VERSION(major, minor, micro) ((major) == XEME_MAJOR_VERSION && \
((minor) < XEME_MINOR_VERSION || \
@@ -155,7 +210,7 @@
* Returns: %NULL if the versions are compatible, or a string describing
* the version mismatch if not compatible.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_AVAILABLE_IN_ALL
const char *xeme_check_version(guint required_major, guint required_minor, guint required_micro);
@@ -165,7 +220,7 @@
*
* The full version string of the running xeme.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_VAR const char *xeme_version;
@@ -176,7 +231,7 @@
* which expands at compile time to the major version of xeme being compiled
* against.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_VAR const guint xeme_major_version;
@@ -187,7 +242,7 @@
* which expands at compile time to the minor version of xeme being compiled
* against.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_VAR const guint xeme_minor_version;
@@ -198,7 +253,7 @@
* which expands at compile time to the micro version of xeme being compiled
* against.
*
- * Since: 0.1.0
+ * Since: 0.1
*/
XEME_VAR const guint xeme_micro_version;