GNOME.org
 

[vte] docs: Small docs fixes

commit 15d67dc21f2e484fe1c400159839fa58b11bf595
Author: Christian Persch <chpe src gnome org>
Date:   Wed Feb 24 19:46:44 2021 +0100

    docs: Small docs fixes

 doc/reference/Makefile.docs       |  2 ++
 doc/reference/vte-sections.txt.in | 12 +++++++++---
 src/parser.cc                     | 10 +++++-----
 src/ring.hh                       |  6 ++++--
 src/vte/vteenums.h                |  2 ++
 src/vte/vteversion.h.in           |  4 ++--
 src/vteaccess.cc                  |  8 --------
 src/vtegtk.cc                     | 33 ++++++++++++++++++---------------
 src/vtepty.cc                     | 11 ++++++-----
 src/vteregex.cc                   | 12 +++++++-----
 10 files changed, 55 insertions(+), 45 deletions(-)
---
diff --git a/doc/reference/Makefile.docs b/doc/reference/Makefile.docs
index 7193bd16..b18f0a41 100644
--- a/doc/reference/Makefile.docs
+++ b/doc/reference/Makefile.docs
@@ -116,6 +116,7 @@ CFILE_GLOB = \
 EXTRA_HFILES =
 
 IGNORE_HFILES = \
+       box_drawing.h \
        buffer.h \
        caps.hh \
        cell.hh \
@@ -141,6 +142,7 @@ IGNORE_HFILES = \
        parser-string.hh \
        ring.hh \
        tabstops.hh \
+       vteaccess.h \
        vteconv.h \
        vtedraw.h \
        vteinternal.hh \
diff --git a/doc/reference/vte-sections.txt.in b/doc/reference/vte-sections.txt.in
index 84afe8c3..53079292 100644
--- a/doc/reference/vte-sections.txt.in
+++ b/doc/reference/vte-sections.txt.in
@@ -88,8 +88,8 @@ vte_terminal_set_word_char_exceptions
 vte_terminal_get_word_char_exceptions
 vte_terminal_set_input_enabled
 vte_terminal_get_input_enabled
-vte_terminal_get_sixel_enabled
-vte_terminal_set_sixel_enabled
+vte_terminal_get_enable_sixel
+vte_terminal_set_enable_sixel
 vte_terminal_write_contents_sync
 vte_terminal_search_find_next
 vte_terminal_search_find_previous
@@ -181,6 +181,9 @@ vte_terminal_feed_child_binary
 <SUBSECTION Private>
 VteCharAttributes
 VteTerminalClassPrivate
+vte_set_test_flags
+VTE_TEST_FLAGS_ALL
+VTE_TEST_FLAGS_NONE
 </SECTION>
 
 <SECTION>
@@ -193,12 +196,16 @@ vte_regex_new_for_match
 vte_regex_new_for_search
 vte_regex_jit
 vte_regex_substitute
+VteRegexError
 
 <SUBSECTION Standard>
 VTE_TYPE_REGEX
 vte_regex_get_type
+VTE_TYPE_REGEX_ERROR
+vte_regex_error_get_type
 VTE_REGEX_ERROR
 vte_regex_error_quark
+VTE_REGEX_FLAGS_DEFAULT
 </SECTION>
 
 <SECTION>
@@ -213,7 +220,6 @@ vte_pty_child_setup
 vte_pty_get_fd
 vte_pty_set_size
 vte_pty_get_size
-vte_pty_set_term
 vte_pty_set_utf8
 
 <SUBSECTION>
diff --git a/src/parser.cc b/src/parser.cc
index 1786ed7d..550e196a 100644
--- a/src/parser.cc
+++ b/src/parser.cc
@@ -615,9 +615,9 @@ parser_transition(vte_parser_t* parser,
 
 #endif // (inline) functions or macros
 
-/**
- * vte_parser_init() - Initialise parser object
- * @parser: the struct vte_parser
+/*
+ * vte_parser_init:
+ * @parser:
  */
 void
 vte_parser_init(vte_parser_t* parser)
@@ -627,8 +627,8 @@ vte_parser_init(vte_parser_t* parser)
 }
 
 /**
- * vte_parser_deinit() - Deinitialises parser object
- * @parser: parser object to deinitialise
+ * vte_parser_deinit:
+ * @parser:
  */
 void
 vte_parser_deinit(vte_parser_t* parser)
diff --git a/src/ring.hh b/src/ring.hh
index 9b38a480..54223904 100644
--- a/src/ring.hh
+++ b/src/ring.hh
@@ -44,8 +44,10 @@ namespace vte {
 
 namespace base {
 
-/**
- * ring: A scrollback buffer ring
+/*
+ * Ring:
+ *
+ * A scrollback buffer ring.
  */
 class Ring {
 public:
diff --git a/src/vte/vteenums.h b/src/vte/vteenums.h
index 561ac918..e6de6622 100644
--- a/src/vte/vteenums.h
+++ b/src/vte/vteenums.h
@@ -181,6 +181,7 @@ typedef enum {
  * @VTE_FEATURE_FLAG_ICU: whether VTE was built with ICU support
  * @VTE_FEATURE_FLAG_SYSTEMD: whether VTE was built with systemd support
  * @VTE_FEATURE_FLAG_SIXEL: whether VTE was built with SIXEL support
+ * @VTE_FEATURE_FLAGS_MASK: mask of all feature flags
  *
  * An enumeration type for features.
  *
@@ -191,6 +192,7 @@ typedef enum /*< skip >*/ {
         VTE_FEATURE_FLAG_ICU     = 1ULL << 1,
         VTE_FEATURE_FLAG_SYSTEMD = 1ULL << 2,
         VTE_FEATURE_FLAG_SIXEL   = 1ULL << 3,
+
         VTE_FEATURE_FLAGS_MASK   = 0xFFFFFFFFFFFFFFFFULL, /* force enum to 64 bit */
 } VteFeatureFlags;
 
diff --git a/src/vte/vteversion.h.in b/src/vte/vteversion.h.in
index 2323f16a..4316da80 100644
--- a/src/vte/vteversion.h.in
+++ b/src/vte/vteversion.h.in
@@ -65,8 +65,8 @@ G_BEGIN_DECLS
  * @micro: required micro version
  *
  * Macro to check the library version at compile time.
- * It returns %1 if the version of VTE is greater or
- * equal to the required one, and %0 otherwise.
+ * It returns <literal>1</literal> if the version of VTE is greater or
+ * equal to the required one, and <literal>0</literal> otherwise.
  */
 #define VTE_CHECK_VERSION(major,minor,micro) \
   (VTE_MAJOR_VERSION > (major) || \
diff --git a/src/vteaccess.cc b/src/vteaccess.cc
index 87633a06..c67afc40 100644
--- a/src/vteaccess.cc
+++ b/src/vteaccess.cc
@@ -15,14 +15,6 @@
  * along with this library.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-/*
- * SECTION: vte-access
- * @short_description: Accessibility peer of #VteTerminal
- *
- * The accessibility peer of a #VteTerminal, implementing GNOME's accessibility
- * framework.
- */
-
 #include "config.h"
 
 #include <atk/atk.h>
diff --git a/src/vtegtk.cc b/src/vtegtk.cc
index 86f0f682..1f35e749 100644
--- a/src/vtegtk.cc
+++ b/src/vtegtk.cc
@@ -1322,7 +1322,7 @@ vte_terminal_class_init(VteTerminalClass *klass)
          * VteTerminal::window-title-changed:
          * @vteterminal: the object which received the signal
          *
-         * Emitted when the terminal's %window_title field is modified.
+         * Emitted when the #VteTerminal:window-title property is modified.
          */
         signals[SIGNAL_WINDOW_TITLE_CHANGED] =
                 g_signal_new(I_("window-title-changed"),
@@ -2015,7 +2015,7 @@ vte_terminal_class_init(VteTerminalClass *klass)
          * VteTerminal:cursor-blink-mode:
          *
          * Sets whether or not the cursor will blink. Using %VTE_CURSOR_BLINK_SYSTEM
-         * will use the #GtkSettings::gtk-cursor-blink setting.
+         * will use the #GtkSettings:gtk-cursor-blink setting.
          */
         pspecs[PROP_CURSOR_BLINK_MODE] =
                 g_param_spec_enum ("cursor-blink-mode", NULL, NULL,
@@ -2538,7 +2538,7 @@ vte_get_user_shell (void) noexcept
 }
 
 /**
- * vte_set_test_flags: (skip):
+ * vte_set_test_flags: (skip)
  * @flags: flags
  *
  * Sets test flags. This function is only useful for implementing
@@ -2770,7 +2770,7 @@ catch (...)
  *
  * Returns: -1
  *
- * Deprecated: 0.46: Use vte_terminal_match_add_regex() or vte_terminal_match_add_regex_full() instead.
+ * Deprecated: 0.46: Use vte_terminal_match_add_regex() instead.
  */
 int
 vte_terminal_match_add_gregex(VteTerminal *terminal,
@@ -2792,7 +2792,8 @@ vte_terminal_match_add_gregex(VteTerminal *terminal,
  * user moves the mouse cursor over a section of displayed text which matches
  * this expression, the text will be highlighted.
  *
- * Note that @regex should have been created using the %PCRE2_MULTILINE flag.
+ * Note that @regex should have been created using the <literal>PCRE2_MULTILINE</literal>
+ * flag.
  *
  * Returns: an integer associated with this expression
  *
@@ -2992,7 +2993,8 @@ catch (...)
  * %NULL is stored there.  Each non-%NULL element of @matches should be freed with
  * g_free().
  *
- * Note that the regexes in @regexes should have been created using the %PCRE2_MULTILINE flag.
+ * Note that the regexes in @regexes should have been created using the
+ * <literal>PCRE2_MULTILINE</literal> flag.
  *
  * Returns: %TRUE iff any of the regexes produced a match
  *
@@ -3233,7 +3235,8 @@ catch (...)
  *
  * Sets the regex to search for. Unsets the search regex when passed %NULL.
  *
- * Note that @regex should have been created using the %PCRE2_MULTILINE flag.
+ * Note that @regex should have been created using the
+ * <literal>PCRE2_MULTILINE</literal> flag.
  *
  * Since: 0.46
  */
@@ -3716,7 +3719,7 @@ spawn_async_cb(GObject *source,
  * @timeout: a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely
  * @cancellable: (allow-none): a #GCancellable, or %NULL
  * @callback: (nullable) (scope async): a #VteTerminalSpawnAsyncCallback, or %NULL
- * @user_data: (closure callback): user data for @callback, or %NULL
+ * @user_data: (nullable) (closure callback): user data for @callback, or %NULL
  *
  * A convenience function that wraps creating the #VtePty and spawning
  * the child process on it. See vte_pty_new_sync(), vte_pty_spawn_with_fds_async(),
@@ -3831,7 +3834,7 @@ catch (...)
  * @timeout: a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely
  * @cancellable: (allow-none): a #GCancellable, or %NULL
  * @callback: (nullable) (scope async): a #VteTerminalSpawnAsyncCallback, or %NULL
- * @user_data: (closure callback): user data for @callback, or %NULL
+ * @user_data: (nullable) (closure callback): user data for @callback, or %NULL
  *
  * A convenience function that wraps creating the #VtePty and spawning
  * the child process on it. Like vte_terminal_spawn_with_fds_async(),
@@ -3984,7 +3987,7 @@ warn_if_callback(VteSelectionFunc func) noexcept
  * @terminal: a #VteTerminal
  * @is_selected: (scope call) (allow-none): a #VteSelectionFunc callback
  * @user_data: (closure): user data to be passed to the callback
- * @attributes: (out caller-allocates) (transfer full) (array) (element-type Vte.CharAttributes): location 
for storing text attributes
+ * @attributes: (nullable) (out caller-allocates) (transfer full) (array) (element-type Vte.CharAttributes): 
location for storing text attributes
  *
  * Extracts a view of the visible part of the terminal.  If @is_selected is not
  * %NULL, characters will only be read if @is_selected returns %TRUE after being
@@ -3995,7 +3998,7 @@ warn_if_callback(VteSelectionFunc func) noexcept
  * This method is unaware of BiDi. The columns returned in @attributes are
  * logical columns.
  *
- * Returns: (transfer full): a newly allocated text string, or %NULL.
+ * Returns: (transfer full) (nullable): a newly allocated text string, or %NULL.
  */
 char *
 vte_terminal_get_text(VteTerminal *terminal,
@@ -4056,7 +4059,7 @@ vte_terminal_get_text_include_trailing_spaces(VteTerminal *terminal,
  * @end_col: last column to search for data
  * @is_selected: (scope call) (allow-none): a #VteSelectionFunc callback
  * @user_data: (closure): user data to be passed to the callback
- * @attributes: (out caller-allocates) (transfer full) (array) (element-type Vte.CharAttributes): location 
for storing text attributes
+ * @attributes: (nullable) (out caller-allocates) (transfer full) (array) (element-type Vte.CharAttributes): 
location for storing text attributes
  *
  * Extracts a view of the visible part of the terminal.  If @is_selected is not
  * %NULL, characters will only be read if @is_selected returns %TRUE after being
@@ -4069,7 +4072,7 @@ vte_terminal_get_text_include_trailing_spaces(VteTerminal *terminal,
  * This method is unaware of BiDi. The columns passed in @start_col and @end_row,
  * and returned in @attributes are logical columns.
  *
- * Returns: (transfer full): a newly allocated text string, or %NULL.
+ * Returns: (transfer full) (nullable): a newly allocated text string, or %NULL.
  */
 char *
 vte_terminal_get_text_range(VteTerminal *terminal,
@@ -5976,7 +5979,7 @@ catch (...)
 /**
  * vte_terminal_set_clear_background:
  * @terminal: a #VteTerminal
- * @setting:
+ * @setting: whether to clear the background
  *
  * Sets whether to paint the background with the background colour.
  * The default is %TRUE.
@@ -6003,7 +6006,7 @@ catch (...)
 /**
  * vte_terminal_get_color_background_for_draw:
  * @terminal: a #VteTerminal
- * @color: (out): a location to store a #GdbRGBA color
+ * @color: (out): a location to store a #GdkRGBA color
  *
  * Returns the background colour, as used by @terminal when
  * drawing the background, which may be different from
diff --git a/src/vtepty.cc b/src/vtepty.cc
index 0bb193c3..3d9ae1fb 100644
--- a/src/vtepty.cc
+++ b/src/vtepty.cc
@@ -151,7 +151,7 @@ catch (...)
  * @error: (allow-none): return location to store a #GError, or %NULL
  *
  * Attempts to resize the pseudo terminal's window size.  If successful, the
- * OS kernel will send #SIGWINCH to the child process group.
+ * OS kernel will send <literal>SIGWINCH</literal> to the child process group.
  *
  * If setting the window size failed, @error will be set to a #GIOError.
  *
@@ -503,8 +503,9 @@ vte_pty_error_quark(void) noexcept
  * Note that you should set the PTY's size using vte_pty_set_size() before
  * spawning the child process, so that the child process has the correct
  * size from the start instead of starting with a default size and then
- * shortly afterwards receiving a SIGWINCH signal. You should prefer
- * using vte_terminal_pty_new_sync() which does this automatically.
+ * shortly afterwards receiving a <literal>SIGWINCH</literal> signal. You
+ * should prefer using vte_terminal_pty_new_sync() which does this
+ * automatically.
  *
  * Returns: (transfer full): a new #VtePty, or %NULL on error with @error filled in
  */
@@ -735,7 +736,7 @@ _vte_pty_check_envv(char const* const* strv) noexcept
  * @timeout: a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely
  * @cancellable: (allow-none): a #GCancellable, or %NULL
  * @callback: (nullable) (scope async): a #GAsyncReadyCallback, or %NULL
- * @user_data: (closure callback): user data for @callback
+ * @user_data: (nullable) closure callback): user data for @callback
  *
  * Starts the specified command under the pseudo-terminal @pty.
  * The @argv and @envv lists should be %NULL-terminated.
@@ -855,7 +856,7 @@ catch (...)
  * @timeout: a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely
  * @cancellable: (allow-none): a #GCancellable, or %NULL
  * @callback: (nullable) (scope async): a #GAsyncReadyCallback, or %NULL
- * @user_data: (closure callback): user data for @callback
+ * @user_data: (nullable) (closure callback): user data for @callback
  *
  * Like vte_pty_spawn_with_fds_async(), except that this function does not
  * allow passing file descriptors to the child process. See vte_pty_spawn_with_fds_async()
diff --git a/src/vteregex.cc b/src/vteregex.cc
index 81b4fb84..e8deabf8 100644
--- a/src/vteregex.cc
+++ b/src/vteregex.cc
@@ -113,8 +113,8 @@ catch (...)
  * See man:pcre2pattern(3) for information
  * about the supported regex language.
  *
- * The regex will be compiled using %PCRE2_UTF and possibly other flags, in
- * addition to the flags supplied in @flags.
+ * The regex will be compiled using <literal>PCRE2_UTF</literal> and
+ * possibly other flags, in addition to the flags supplied in @flags.
  *
  * Returns: (transfer full): a newly created #VteRegex, or %NULL with @error filled in
  */
@@ -151,8 +151,8 @@ catch (...)
  * See man:pcre2pattern(3) for information
  * about the supported regex language.
  *
- * The regex will be compiled using %PCRE2_UTF and possibly other flags, in
- * addition to the flags supplied in @flags.
+ * The regex will be compiled using <literal>PCRE2_UTF</literal> and
+ * possibly other flags, in addition to the flags supplied in @flags.
  *
  * Returns: (transfer full): a newly created #VteRegex, or %NULL with @error filled in
  */
@@ -178,6 +178,8 @@ catch (...)
 /**
  * vte_regex_jit:
  * @regex: a #VteRegex
+ * @flags: PCRE2 JIT flags, or 0
+ * @error: (nullable): return location for a #GError, or %NULL
  *
  * If the platform supports JITing, JIT compiles @regex.
  *
@@ -224,7 +226,7 @@ _vte_regex_has_multiline_compile_flag(VteRegex *regex)
  * @flags: PCRE2 match flags
  * @error: (nullable): return location for a #GError, or %NULL
  *
- * See man:pcre2api(3) on pcre2_substitute() for more information.
+ * See man:pcre2api(3) and man:pcre2_substitute(3) for more information.
  *
  * Returns: (transfer full): the substituted string, or %NULL
  *   if an error occurred
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]