GNOME.org
 

[gtksourceview] docs: add (nullable) annotations to many return values

commit 75e152e12965498f11e7988309e2548d25f8993f
Author: Evan Nemerson <evan nemerson com>
Date:   Wed Aug 13 14:14:57 2014 -0700

    docs: add (nullable) annotations to many return values
    
    These are just for functions which mention %NULL in the Returns:
    section, as well as methods which were previously marked as nullable
    in the Vala bindings.

 gtksourceview/GtkSource-3.0.metadata        |    3 ---
 gtksourceview/gtksourcebuffer.c             |    3 ++-
 gtksourceview/gtksourcecompletionprovider.c |    7 ++++---
 gtksourceview/gtksourceencoding.c           |    3 ++-
 gtksourceview/gtksourcelanguagemanager.c    |   23 +++++++++++------------
 gtksourceview/gtksourcemark.c               |    4 ++--
 gtksourceview/gtksourcesearchcontext.c      |    2 +-
 gtksourceview/gtksourcesearchsettings.c     |    2 +-
 gtksourceview/gtksourcestylescheme.c        |   24 ++++++++++++------------
 9 files changed, 35 insertions(+), 36 deletions(-)
---
diff --git a/gtksourceview/GtkSource-3.0.metadata b/gtksourceview/GtkSource-3.0.metadata
index a02f4e0..1c5c57b 100644
--- a/gtksourceview/GtkSource-3.0.metadata
+++ b/gtksourceview/GtkSource-3.0.metadata
@@ -5,12 +5,9 @@ Completion
         .show#method name="start"
 CompletionProvider
         .*#virtual_method virtual
-        .get_icon nullable
-        .get_info_widget nullable
 CompletionProposal
         .equal#virtual_method virtual
         .get_icon#virtual_method virtual
         .hash#virtual_method virtual
 SearchContext
-        .get_regex_error nullable
         .regex_error type="GLib.Error?"
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index bcb494a..276af8b 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -2474,7 +2474,8 @@ gtk_source_buffer_set_undo_manager (GtkSourceBuffer      *buffer,
  * see gtk_source_buffer_set_undo_manager().  The returned object should not be
  * unreferenced by the user.
  *
- * Returns: (transfer none): the #GtkSourceUndoManager associated with the buffer, or %NULL.
+ * Returns: (nullable) (transfer none): the #GtkSourceUndoManager associated
+ * with the buffer, or %NULL.
  **/
 GtkSourceUndoManager *
 gtk_source_buffer_get_undo_manager (GtkSourceBuffer *buffer)
diff --git a/gtksourceview/gtksourcecompletionprovider.c b/gtksourceview/gtksourcecompletionprovider.c
index 6b537ad..cba838e 100644
--- a/gtksourceview/gtksourcecompletionprovider.c
+++ b/gtksourceview/gtksourcecompletionprovider.c
@@ -160,7 +160,7 @@ gtk_source_completion_provider_get_name (GtkSourceCompletionProvider *provider)
  *
  * Get the icon of the provider.
  *
- * Returns: (transfer none): The icon to be used for the provider,
+ * Returns: (nullable) (transfer none): The icon to be used for the provider,
  *          or %NULL if the provider does not have a special icon.
  */
 GdkPixbuf *
@@ -245,8 +245,9 @@ gtk_source_completion_provider_match (GtkSourceCompletionProvider *provider,
  *   </para>
  * </note>
  *
- * Returns: (transfer none): a custom #GtkWidget to show extra
- * information about @proposal.
+ * Returns: (nullable) (transfer none): a custom #GtkWidget to show extra
+ * information about @proposal, or %NULL if the provider does not have a special
+ * info widget.
  */
 GtkWidget *
 gtk_source_completion_provider_get_info_widget (GtkSourceCompletionProvider *provider,
diff --git a/gtksourceview/gtksourceencoding.c b/gtksourceview/gtksourceencoding.c
index daabb20..ab4b15b 100644
--- a/gtksourceview/gtksourceencoding.c
+++ b/gtksourceview/gtksourceencoding.c
@@ -306,7 +306,8 @@ gtk_source_encoding_lazy_init (void)
  * Gets a #GtkSourceEncoding from a character set such as "UTF-8" or
  * "ISO-8859-1".
  *
- * Returns: the corresponding #GtkSourceEncoding, or %NULL if not found.
+ * Returns: (nullable): the corresponding #GtkSourceEncoding, or %NULL
+ * if not found.
  * Since: 3.14
  */
 const GtkSourceEncoding *
diff --git a/gtksourceview/gtksourcelanguagemanager.c b/gtksourceview/gtksourcelanguagemanager.c
index 77c5c3c..86767b2 100644
--- a/gtksourceview/gtksourcelanguagemanager.c
+++ b/gtksourceview/gtksourcelanguagemanager.c
@@ -405,12 +405,11 @@ ensure_languages (GtkSourceLanguageManager *lm)
  *
  * Returns the ids of the available languages.
  *
- * Returns: (transfer none): a %NULL-terminated array of string
- * containing the ids of the available languages or %NULL if
- * no language is available.
- * The array is sorted alphabetically according to the language
- * name.
- * The array is owned by @lm and must not be modified.
+ * Returns: (nullable) (transfer none): a %NULL-terminated array of
+ * string containing the ids of the available languages or %NULL if no
+ * language is available.  The array is sorted alphabetically
+ * according to the language name.  The array is owned by @lm and must
+ * not be modified.
  */
 const gchar * const *
 gtk_source_language_manager_get_language_ids (GtkSourceLanguageManager *lm)
@@ -430,9 +429,9 @@ gtk_source_language_manager_get_language_ids (GtkSourceLanguageManager *lm)
  * Gets the #GtkSourceLanguage identified by the given @id in the language
  * manager.
  *
- * Returns: (transfer none): a #GtkSourceLanguage, or %NULL if there is no language
- * identified by the given @id. Return value is owned by @lm and should not
- * be freed.
+ * Returns: (nullable) (transfer none): a #GtkSourceLanguage, or %NULL
+ * if there is no language identified by the given @id. Return value is
+ * owned by @lm and should not be freed.
  */
 GtkSourceLanguage *
 gtk_source_language_manager_get_language (GtkSourceLanguageManager *lm,
@@ -629,9 +628,9 @@ pick_lang_for_mime_type (GtkSourceLanguageManager *lm,
  * etc. Use gtk_source_language_get_mime_types() and gtk_source_language_get_globs()
  * if you need full control over file -> language mapping.
  *
- * Returns: (transfer none): a #GtkSourceLanguage, or %NULL if there is no suitable language
- * for given @filename and/or @content_type. Return value is owned by @lm
- * and should not be freed.
+ * Returns: (nullable) (transfer none): a #GtkSourceLanguage, or %NULL if there
+ * is no suitable language for given @filename and/or @content_type. Return
+ * value is owned by @lm and should not be freed.
  *
  * Since: 2.4
  */
diff --git a/gtksourceview/gtksourcemark.c b/gtksourceview/gtksourcemark.c
index af14bdc..ccd8ddc 100644
--- a/gtksourceview/gtksourcemark.c
+++ b/gtksourceview/gtksourcemark.c
@@ -208,7 +208,7 @@ gtk_source_mark_get_category (GtkSourceMark *mark)
  *
  * If @category is %NULL, looks for marks of any category.
  *
- * Returns: (transfer none): the next #GtkSourceMark, or %NULL.
+ * Returns: (nullable) (transfer none): the next #GtkSourceMark, or %NULL.
  *
  * Since: 2.2
  */
@@ -242,7 +242,7 @@ gtk_source_mark_next (GtkSourceMark *mark,
  *
  * If @category is %NULL, looks for marks of any category
  *
- * Returns: (transfer none): the previous #GtkSourceMark, or %NULL.
+ * Returns: (nullable) (transfer none): the previous #GtkSourceMark, or %NULL.
  *
  * Since: 2.2
  */
diff --git a/gtksourceview/gtksourcesearchcontext.c b/gtksourceview/gtksourcesearchcontext.c
index 04cf4f8..9580e9e 100644
--- a/gtksourceview/gtksourcesearchcontext.c
+++ b/gtksourceview/gtksourcesearchcontext.c
@@ -2973,7 +2973,7 @@ gtk_source_search_context_set_highlight (GtkSourceSearchContext *search,
  *
  * Free the return value with g_error_free().
  *
- * Returns: the #GError, or %NULL if the pattern is valid.
+ * Returns: (nullable): the #GError, or %NULL if the pattern is valid.
  * Since: 3.10
  */
 GError *
diff --git a/gtksourceview/gtksourcesearchsettings.c b/gtksourceview/gtksourcesearchsettings.c
index 85b4b80..7778ea9 100644
--- a/gtksourceview/gtksourcesearchsettings.c
+++ b/gtksourceview/gtksourcesearchsettings.c
@@ -306,7 +306,7 @@ gtk_source_search_settings_set_search_text (GtkSourceSearchSettings *settings,
  * You may be interested to call gtk_source_utils_escape_search_text() after
  * this function.
  *
- * Returns: the text to search, or %NULL if the search is disabled.
+ * Returns: (nullable): the text to search, or %NULL if the search is disabled.
  * Since: 3.10
  */
 const gchar *
diff --git a/gtksourceview/gtksourcestylescheme.c b/gtksourceview/gtksourcestylescheme.c
index 90d3456..55a8725 100644
--- a/gtksourceview/gtksourcestylescheme.c
+++ b/gtksourceview/gtksourcestylescheme.c
@@ -317,7 +317,7 @@ gtk_source_style_scheme_get_name (GtkSourceStyleScheme *scheme)
  * gtk_source_style_scheme_get_description:
  * @scheme: a #GtkSourceStyleScheme.
  *
- * Returns: @scheme description (if defined), or %NULL.
+ * Returns: (nullable): @scheme description (if defined), or %NULL.
  *
  * Since: 2.0
  */
@@ -333,9 +333,9 @@ gtk_source_style_scheme_get_description (GtkSourceStyleScheme *scheme)
  * gtk_source_style_scheme_get_authors:
  * @scheme: a #GtkSourceStyleScheme.
  *
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated
- * array containing the @scheme authors or %NULL if no author
- * is specified by the style scheme.
+ * Returns: (nullable) (array zero-terminated=1) (transfer none): a
+ * %NULL-terminated array containing the @scheme authors or %NULL if
+ * no author is specified by the style scheme.
  *
  * Since: 2.0
  */
@@ -356,8 +356,8 @@ gtk_source_style_scheme_get_authors (GtkSourceStyleScheme *scheme)
  * gtk_source_style_scheme_get_filename:
  * @scheme: a #GtkSourceStyleScheme.
  *
- * Returns: @scheme file name if the scheme was created parsing a
- * style scheme file or %NULL in the other cases.
+ * Returns: (nullable): @scheme file name if the scheme was created
+ * parsing a style scheme file or %NULL in the other cases.
  *
  * Since: 2.0
  */
@@ -496,9 +496,9 @@ fix_style_colors (GtkSourceStyleScheme *scheme,
  * @scheme: a #GtkSourceStyleScheme.
  * @style_id: id of the style to retrieve.
  *
- * Returns: (transfer none): style which corresponds to @style_id
- * in the @scheme, or %NULL when no style with this name found.
- * It is owned by @scheme and may not be unref'ed.
+ * Returns: (nullable) (transfer none): style which corresponds to @style_id in
+ * the @scheme, or %NULL when no style with this name found.  It is owned by
+ * @scheme and may not be unref'ed.
  *
  * Since: 2.0
  */
@@ -1176,8 +1176,8 @@ parse_style_scheme_element (GtkSourceStyleScheme *scheme,
  * _gtk_source_style_scheme_new_from_file:
  * @filename: file to parse.
  *
- * Returns: new #GtkSourceStyleScheme created from file, or
- * %NULL on error.
+ * Returns: (nullable): new #GtkSourceStyleScheme created from file,
+ * or %NULL on error.
  *
  * Since: 2.0
  */
@@ -1257,7 +1257,7 @@ _gtk_source_style_scheme_new_from_file (const gchar *filename)
  * _gtk_source_style_scheme_get_parent_id:
  * @scheme: a #GtkSourceStyleScheme.
  *
- * Returns: parent style scheme id or %NULL.
+ * Returns: (nullable): parent style scheme id or %NULL.
  *
  * Since: 2.0
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]