xeme/xeme

Add a doc check unit test and fix the issues it found

8 weeks ago, Gary Kramlich
0822a5847e59
Parents 033661d58d65
Children 5d0707ab10a2
Add a doc check unit test and fix the issues it found

Testing Done:
Ran the unit tests.

Reviewed at https://reviews.imfreedom.org/r/3042/
9 files changed, 76 insertions(+), 75 deletions(-)
  • +10 -0
    xeme/reference/meson.build
  • +24 -0
    xeme/reference/xeme.toml.in
  • +4 -0
    xeme/xemeextension.h
  • +2 -0
    xeme/xemeextensionmap.h
  • +2 -2
    xeme/xemeinputstream.h
  • +3 -3
    xeme/xememessage.h
  • +5 -3
    xeme/xemeoutputstream.h
  • +6 -8
    xeme/xemestream.h
  • +20 -59
    xeme/xemeversion.h
    • --- a/xeme/reference/meson.build Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/reference/meson.build Wed Mar 20 23:28:27 2024 -0500
    @@ -31,4 +31,14 @@
    install_dir : docs_dir,
    )
    +test('doc-check',
    + gidocgen,
    + args: [
    + 'check',
    + '--config', xeme_gidocgen_toml,
    + xeme_gir[0],
    + ],
    + depends: xeme_gir[0],
    +)
    +
    doc_targets += xeme_doc
    --- a/xeme/reference/xeme.toml.in Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/reference/xeme.toml.in Wed Mar 20 23:28:27 2024 -0500
    @@ -39,3 +39,27 @@
    content_files = []
    content_images = []
    urlmap_file = "urlmap.js"
    +
    +[[object]]
    +pattern = "DEPRECATED_IN_*"
    +hidden = true
    +
    +[[object]]
    +name = "DEPRECATED_FOR"
    +hidden = true
    +
    +[[object]]
    +name = "UNAVAILABLE"
    +hidden = true
    +
    +[[object]]
    +name = "UNAVAILABLE_MACRO"
    +hidden = true
    +
    +[[object]]
    +name = "UNAVAILABLE_STATIC_INLINE"
    +hidden = true
    +
    +[[object]]
    +name = "UNAVAILABLE_TYPE"
    +hidden = true
    \ No newline at end of file
    --- a/xeme/xemeextension.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xemeextension.h Wed Mar 20 23:28:27 2024 -0500
    @@ -63,6 +63,8 @@
    *
    * Gets the name of the element from @extension.
    *
    + * Returns: The name of the element of the extension.
    + *
    * Since: 0.1
    */
    XEME_AVAILABLE_IN_0_1
    @@ -74,6 +76,8 @@
    *
    * Gets the namespace from @extension.
    *
    + * Returns: The namespace of the extension.
    + *
    * Since: 0.1
    */
    XEME_AVAILABLE_IN_0_1
    --- a/xeme/xemeextensionmap.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xemeextensionmap.h Wed Mar 20 23:28:27 2024 -0500
    @@ -48,6 +48,8 @@
    *
    * Creates a new extension map.
    *
    + * Returns: (transfer full): The new instance.
    + *
    * Since: 0.1
    */
    XEME_AVAILABLE_IN_0_1
    --- a/xeme/xemeinputstream.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xemeinputstream.h Wed Mar 20 23:28:27 2024 -0500
    @@ -30,8 +30,6 @@
    G_BEGIN_DECLS
    -#define XEME_TYPE_INPUT_STREAM (xeme_input_stream_get_type())
    -
    /**
    * XemeInputStream:
    *
    @@ -40,6 +38,8 @@
    * Since: 0.1
    */
    +#define XEME_TYPE_INPUT_STREAM (xeme_input_stream_get_type())
    +
    XEME_AVAILABLE_IN_0_1
    G_DECLARE_DERIVABLE_TYPE(XemeInputStream, xeme_input_stream, XEME, INPUT_STREAM, XemeStream)
    --- a/xeme/xememessage.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xememessage.h Wed Mar 20 23:28:27 2024 -0500
    @@ -26,16 +26,16 @@
    G_BEGIN_DECLS
    -#define XEME_TYPE_MESSAGE (xeme_message_get_type())
    -
    /**
    * XemeMessage:
    *
    - * An XMPP message stanza.
    + * An XMPP Message stanza.
    *
    * Since: 0.1
    */
    +#define XEME_TYPE_MESSAGE (xeme_message_get_type())
    +
    XEME_AVAILABLE_IN_0_1
    G_DECLARE_FINAL_TYPE(XemeMessage, xeme_message, XEME, MESSAGE, XemeStanza)
    --- a/xeme/xemeoutputstream.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xemeoutputstream.h Wed Mar 20 23:28:27 2024 -0500
    @@ -28,16 +28,17 @@
    G_BEGIN_DECLS
    -#define XEME_TYPE_OUTPUT_STREAM (xeme_output_stream_get_type())
    -
    /**
    * XemeOutputStream:
    *
    - * A stream to send XMPP stanzas to a remote connection.
    + * An XMPP output stream. This is used to send stanzas to the other end of the
    + * connection.
    *
    * Since: 0.1
    */
    +#define XEME_TYPE_OUTPUT_STREAM (xeme_output_stream_get_type())
    +
    XEME_AVAILABLE_IN_0_1
    G_DECLARE_FINAL_TYPE(XemeOutputStream, xeme_output_stream, XEME, OUTPUT_STREAM, XemeStream)
    @@ -46,6 +47,7 @@
    * @to: The jid of the recipient.
    * @from: The jid of the sender.
    * @cancellable: (nullable): A [class@Gio.Cancellable] for the stream.
    + *
    * Creates a new output stream.
    *
    * Returns: (transfer full): The new instance.
    --- a/xeme/xemestream.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xemestream.h Wed Mar 20 23:28:27 2024 -0500
    @@ -30,7 +30,7 @@
    /**
    * XEME_STREAM_PI:
    *
    - * A basic UTF-8 XML Processing Instruction.
    + * A constant for the XML processing instruction with a UTF-8 encoding.
    *
    * Since: 0.1
    */
    @@ -39,7 +39,7 @@
    /**
    * XEME_STREAM_VERSION:
    *
    - * The version of the XMPP stream.
    + * The version of the XMPP stream protocol.
    *
    * Since: 0.1
    */
    @@ -48,7 +48,7 @@
    /**
    * XEME_STREAM_XMLNS:
    *
    - * The value for the default namespace of the XML document.
    + * The XML namespace that is used as the default namespace for the stream.
    *
    * Since: 0.1
    */
    @@ -57,7 +57,7 @@
    /**
    * XEME_STREAM_XMLNS_STREAM:
    *
    - * The value for the stream namespace of the XML document.
    + * The XML namespace that is used for the `streams` namespace.
    *
    * Since: 0.1
    */
    @@ -66,13 +66,11 @@
    /**
    * XemeStream:
    *
    - * A base class for representing XMPP streams.
    - *
    - * This mostly just contains common properties that are needed by
    - * [class@InputStream] and [class@OutputStream].
    + * A base class for all streams.
    *
    * Since: 0.1
    */
    +
    #define XEME_TYPE_STREAM (xeme_stream_get_type())
    XEME_AVAILABLE_IN_0_1
    --- a/xeme/xemeversion.h Sun Feb 18 01:46:40 2024 -0600
    +++ b/xeme/xemeversion.h Wed Mar 20 23:28:27 2024 -0500
    @@ -45,54 +45,6 @@
    #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
    @@ -108,6 +60,26 @@
    #endif
    /**
    + * XEME_VERSION_MIN_REQUIRED:
    + *
    + * A macro that should be defined by the user prior to including the `xeme.h`
    + * header.
    + *
    + * The definition should be one of the predefined Xeme version macros:
    + * %XEME_VERSION_0_1, %XEME_VERSION_0_2, ...
    + *
    + * This macro defines the earliest version of Xeme that the package is required
    + * to be able to compile against.
    + *
    + * If the compiler is configured to warn about the use of deprecated functions,
    + * then using functions that were deprecated in version
    + * %XEME_VERSION_MIN_REQUIRED or earlier will cause warnings (but using
    + * functions deprecated in later releases will not).
    + *
    + * Since: 0.1
    + */
    +
    +/**
    * XEME_VERSION_CUR_STABLE:
    *
    * A macro that evaluates to the current stable version of xeme, in a format
    @@ -118,17 +90,6 @@
    #define XEME_VERSION_CUR_STABLE \
    (G_ENCODE_VERSION(XEME_MAJOR_VERSION, XEME_MINOR_VERSION))
    -/**
    - * 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)
    #elif XEME_VERSION_MIN_REQUIRED == 0