Add @nullable annotations everywhere

src/build.c

@@ -553,7 +553,7 @@ GeanyBuildCommand *build_get_menu_item(GeanyBuildSource src, GeanyBuildGroup grp
  * @param cmd the index of the command within the group.
  * @param fld the field to return
  *
- * @return a pointer to the constant string or @c NULL if it doesn't exist.
+ * @return @nullable a pointer to the constant string or @c NULL if it doesn't exist.
  *         This is a pointer to an internal structure and must not be freed.
  *
  **/

src/dialogs.c

@@ -1058,11 +1058,11 @@ static void on_dialog_input(const gchar *str, gpointer data)
 
 /** Asks the user for text input.
  * @param title Dialog title.
- * @param parent The currently focused window, usually @c geany->main_widgets->window.
+ * @param parent @nullable The currently focused window, usually @c geany->main_widgets->window.
  * 	@c NULL can be used but is discouraged due to window manager effects.
- * @param label_text Label text, or @c NULL.
- * @param default_text Text to display in the input field, or @c NULL.
- * @return New copy of user input or @c NULL if cancelled.
+ * @param label_text @nullable Label text, or @c NULL.
+ * @param default_text @nullable Text to display in the input field, or @c NULL.
+ * @return @nullable New copy of user input or @c NULL if cancelled.
  * @since 0.20. */
 GEANY_API_SYMBOL
 gchar *dialogs_show_input(const gchar *title, GtkWindow *parent, const gchar *label_text,

src/document.c

@@ -146,7 +146,7 @@ static GtkWidget* document_show_message(GeanyDocument *doc, GtkMessageType msgty
  * @param realname The filename to search, which should be identical to the
  * string returned by @c tm_get_real_path().
  *
- * @return @transfer{none} The matching document, or @c NULL.
+ * @return @transfer{none} @nullable The matching document, or @c NULL.
  * @note This is only really useful when passing a @c TMSourceFile::file_name.
  * @see GeanyDocument::real_path.
  * @see document_find_by_filename().
@@ -196,7 +196,7 @@ static gchar *get_real_path_from_utf8(const gchar *utf8_filename)
  *
  *  @param utf8_filename The filename to search (in UTF-8 encoding).
  *
- *  @return @transfer{none} The matching document, or @c NULL.
+ *  @return @transfer{none} @nullable The matching document, or @c NULL.
  *  @see document_find_by_real_path().
  **/
 GEANY_API_SYMBOL
@@ -366,7 +366,7 @@ GeanyDocument *document_get_from_notebook_child(GtkWidget *page)
  *
  *  @param page_num The notebook page number to search.
  *
- *  @return @transfer{none} The corresponding document for the given notebook page, or @c NULL.
+ *  @return @transfer{none} @nullable The corresponding document for the given notebook page, or @c NULL.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_get_from_page(guint page_num)
@@ -385,7 +385,7 @@ GeanyDocument *document_get_from_page(guint page_num)
 /**
  *  Finds the current document.
  *
- *  @return @transfer{none} A pointer to the current document or @c NULL if there are no opened documents.
+ *  @return @transfer{none} @nullable A pointer to the current document or @c NULL if there are no opened documents.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_get_current(void)
@@ -826,9 +826,9 @@ GeanyDocument *document_new_file_if_non_open(void)
  *  Line endings in @a text will be converted to the default setting.
  *  Afterwards, the @c "document-new" signal is emitted for plugins.
  *
- *  @param utf8_filename The file name in UTF-8 encoding, or @c NULL to open a file as "untitled".
- *  @param ft The filetype to set or @c NULL to detect it from @a filename if not @c NULL.
- *  @param text The initial content of the file (in UTF-8 encoding), or @c NULL.
+ *  @param utf8_filename @nullable The file name in UTF-8 encoding, or @c NULL to open a file as "untitled".
+ *  @param ft @nullable The filetype to set or @c NULL to detect it from @a filename if not @c NULL.
+ *  @param text @nullable The initial content of the file (in UTF-8 encoding), or @c NULL.
  *
  *  @return @transfer{none} The new document.
  **/
@@ -911,10 +911,10 @@ GeanyDocument *document_new_file(const gchar *utf8_filename, GeanyFiletype *ft,
  *
  *  @param locale_filename The filename of the document to load, in locale encoding.
  *  @param readonly Whether to open the document in read-only mode.
- *  @param ft The filetype for the document or @c NULL to auto-detect the filetype.
- *  @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
+ *  @param ft @nullable The filetype for the document or @c NULL to auto-detect the filetype.
+ *  @param forced_enc @nullable The file encoding to use or @c NULL to auto-detect the file encoding.
  *
- *  @return @transfer{none} The document opened or @c NULL.
+ *  @return @transfer{none} @nullable The document opened or @c NULL.
  **/
 GEANY_API_SYMBOL
 GeanyDocument *document_open_file(const gchar *locale_filename, gboolean readonly,
@@ -1560,8 +1560,8 @@ void document_open_file_list(const gchar *data, gsize length)
  *
  *  @param filenames @elementtype{filename} A list of filenames to load, in locale encoding.
  *  @param readonly Whether to open the document in read-only mode.
- *  @param ft The filetype for the document or @c NULL to auto-detect the filetype.
- *  @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
+ *  @param ft @nullable The filetype for the document or @c NULL to auto-detect the filetype.
+ *  @param forced_enc @nullable The file encoding to use or @c NULL to auto-detect the file encoding.
  **/
 GEANY_API_SYMBOL
 void document_open_files(const GSList *filenames, gboolean readonly, GeanyFiletype *ft,
@@ -1599,7 +1599,7 @@ static void on_keep_edit_history_on_reload_response(GtkWidget *bar, gint respons
  *  @a forced_enc or @c NULL to auto-detect the file encoding.
  *
  *  @param doc The document to reload.
- *  @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
+ *  @param forced_enc @nullable The file encoding to use or @c NULL to auto-detect the file encoding.
  *
  *  @return @c TRUE if the document was actually reloaded or @c FALSE otherwise.
  **/
@@ -1812,7 +1812,7 @@ gboolean document_need_save_as(GeanyDocument *doc)
  * Saves the document, detecting the filetype.
  *
  * @param doc The document for the file to save.
- * @param utf8_fname The new name for the document, in UTF-8, or NULL.
+ * @param utf8_fname @nullable The new name for the document, in UTF-8, or @c NULL.
  * @return @c TRUE if the file was saved or @c FALSE if the file could not be saved.
  *
  * @see document_save_file().
@@ -3237,8 +3237,8 @@ const gchar *document_get_status_widget_class(GeanyDocument *doc)
  *
  *  @param doc The document to use.
  *
- *  @return The color for the document or @c NULL if the default color should be used. The color
- *          object is owned by Geany and should not be modified or freed.
+ *  @return @nullable The color for the document or @c NULL if the default color should be used.
+ *          The color object is owned by Geany and should not be modified or freed.
  *
  *  @since 0.16
  */
@@ -3290,7 +3290,7 @@ const GdkColor *document_get_status_color(GeanyDocument *doc)
 /** Accessor function for @ref documents_array items.
  * @warning Always check the returned document is valid (@c doc->is_valid).
  * @param idx @c documents_array index.
- * @return @transfer{none} The document, or @c NULL if @a idx is out of range.
+ * @return @transfer{none} @nullable The document, or @c NULL if @a idx is out of range.
  *
  *  @since 0.16
  */

src/editor.c

@@ -1198,7 +1198,7 @@ get_default_indent_prefs(void)
  * Prefs can be different according to project or document.
  * @warning Always get a fresh result instead of keeping a pointer to it if the editor/project
  * settings may have changed, or if this function has been called for a different editor.
- * @param editor The editor, or @c NULL to get the default indent prefs.
+ * @param editor @nullable The editor, or @c NULL to get the default indent prefs.
  * @return The indent prefs. */
 GEANY_API_SYMBOL
 const GeanyIndentPrefs *
@@ -1720,7 +1720,7 @@ void editor_find_current_word_sciwc(GeanyEditor *editor, gint pos, gchar *word,
  *                   as part of a word. May be @c NULL to use the default wordchars,
  *                   see @ref GEANY_WORDCHARS.
  *
- *  @return A newly-allocated string containing the word at the given @a pos or @c NULL.
+ *  @return @nullable A newly-allocated string containing the word at the given @a pos or @c NULL.
  *          Should be freed when no longer needed.
  *
  *  @since 0.16
@@ -4191,7 +4191,7 @@ void editor_insert_color(GeanyEditor *editor, const gchar *colour)
  *  Retrieves the end of line characters mode (LF, CR/LF, CR) in the given editor.
  *  If @a editor is @c NULL, the default end of line characters are used.
  *
- *  @param editor The editor to operate on, or @c NULL to query the default value.
+ *  @param editor @nullable The editor to operate on, or @c NULL to query the default value.
  *  @return The used end of line characters mode.
  *
  *  @since 0.20
@@ -4213,7 +4213,7 @@ gint editor_get_eol_char_mode(GeanyEditor *editor)
  *  (LF, CR/LF, CR) in the given editor.
  *  If @a editor is @c NULL, the default end of line characters are used.
  *
- *  @param editor The editor to operate on, or @c NULL to query the default value.
+ *  @param editor @nullable The editor to operate on, or @c NULL to query the default value.
  *  @return The name of the end of line characters.
  *
  *  @since 0.19
@@ -4235,7 +4235,7 @@ const gchar *editor_get_eol_char_name(GeanyEditor *editor)
  *  If @a editor is @c NULL, the default end of line characters are used.
  *  The returned value is 1 for CR and LF and 2 for CR/LF.
  *
- *  @param editor The editor to operate on, or @c NULL to query the default value.
+ *  @param editor @nullable The editor to operate on, or @c NULL to query the default value.
  *  @return The length of the end of line characters.
  *
  *  @since 0.19
@@ -4261,7 +4261,7 @@ gint editor_get_eol_char_len(GeanyEditor *editor)
  *  If @a editor is @c NULL, the default end of line characters are used.
  *  The returned value is either "\n", "\r\n" or "\r".
  *
- *  @param editor The editor to operate on, or @c NULL to query the default value.
+ *  @param editor @nullable The editor to operate on, or @c NULL to query the default value.
  *  @return The end of line characters.
  *
  *  @since 0.19
@@ -5202,9 +5202,9 @@ void editor_indent(GeanyEditor *editor, gboolean increase)
  * If @a editor is passed, returns a snippet specific to the document filetype.
  * If @a editor is @c NULL, returns a snippet from the default set.
  *
- * @param editor Editor or @c NULL.
+ * @param editor @nullable Editor or @c NULL.
  * @param snippet_name Snippet name.
- * @return snippet or @c NULL if it was not found. Must not be freed.
+ * @return @nullable snippet or @c NULL if it was not found. Must not be freed.
  */
 GEANY_API_SYMBOL
 const gchar *editor_find_snippet(GeanyEditor *editor, const gchar *snippet_name)

src/encodings.c

@@ -260,7 +260,7 @@ const GeanyEncoding *encodings_get_from_index(gint idx)
  *  @param idx @ref GeanyEncodingIndex to retrieve the corresponding character set.
  *
  *
- *  @return The charset according to idx, or @c NULL if the index is invalid.
+ *  @return @nullable The charset according to idx, or @c NULL if the index is invalid.
  *
  *  @since 0.13
  **/
@@ -777,7 +777,7 @@ static gchar *encodings_convert_to_utf8_with_suggestion(const gchar *buffer, gss
  *  @param size the length of the string, or -1 if the string is nul-terminated.
  *  @param used_encoding @out @optional return location of the detected encoding of the input string, or @c NULL.
  *
- *  @return If the conversion was successful, a newly allocated nul-terminated string,
+ *  @return @nullable If the conversion was successful, a newly allocated nul-terminated string,
  *    which must be freed with @c g_free(). Otherwise @c NULL.
  **/
 GEANY_API_SYMBOL

src/filetypes.c

@@ -1253,7 +1253,7 @@ gboolean filetype_has_tags(GeanyFiletype *ft)
 
 /** Finds a filetype pointer from its @a name field.
  * @param name Filetype name.
- * @return @transfer{none} The filetype found, or @c NULL.
+ * @return @transfer{none} @nullable The filetype found, or @c NULL.
  *
  * @since 0.15
  **/
@@ -1499,7 +1499,7 @@ void filetypes_reload_extensions(void)
 /** Accessor function for @ref GeanyData::filetypes_array items.
  * Example: @code ft = filetypes_index(GEANY_FILETYPES_C); @endcode
  * @param idx @c filetypes_array index.
- * @return @transfer{none} The filetype, or @c NULL if @a idx is out of range.
+ * @return @transfer{none} @nullable The filetype, or @c NULL if @a idx is out of range.
  *
  *  @since 0.16
  */

src/keybindings.c

@@ -157,14 +157,14 @@ GeanyKeyBinding *keybindings_get_item(GeanyKeyGroup *group, gsize key_id)
  * future default keybindings.
  * @param group Group.
  * @param key_id Keybinding index for the group.
- * @param callback Function to call when activated, or @c NULL to use the group callback.
+ * @param callback @nullable Function to call when activated, or @c NULL to use the group callback.
  * Usually it's better to use the group callback instead - see plugin_set_key_group().
  * @param key Default key, e.g. @c GDK_j (must be lower case), but usually 0 for unset.
  * @param mod Default modifier, e.g. @c GDK_CONTROL_MASK, but usually 0 for unset.
  * @param kf_name Key name for the configuration file, such as @c "menu_new".
  * @param label Label used in the preferences dialog keybindings tab. May contain
  * underscores - these won't be displayed.
- * @param menu_item Optional widget to set an accelerator for, or @c NULL.
+ * @param menu_item @nullable Optional widget to set an accelerator for, or @c NULL.
  * @return The keybinding - normally this is ignored. */
 GEANY_API_SYMBOL
 GeanyKeyBinding *keybindings_set_item(GeanyKeyGroup *group, gsize key_id,

src/pluginutils.c

@@ -105,7 +105,7 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
 /** @girskip
  * Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
  * @param plugin Must be @ref geany_plugin.
- * @param object Object to connect to, or @c NULL when using @link pluginsignals.c Geany signals @endlink.
+ * @param object @nullable Object to connect to, or @c NULL when using @link pluginsignals.c Geany signals @endlink.
  * @param signal_name The name of the signal. For a list of available
  * signals, please see the @link pluginsignals.c Signal documentation @endlink.
  * @param after Set to @c TRUE to call your handler after the main signal handlers have been called
@@ -300,7 +300,7 @@ guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data)
  * @param plugin Must be @ref geany_plugin.
  * @param section_name Name used in the configuration file, such as @c "html_chars".
  * @param count Number of keybindings for the group.
- * @param callback Group callback, or @c NULL if you only want individual keybinding callbacks.
+ * @param callback @nullable Group callback, or @c NULL if you only want individual keybinding callbacks.
  * @return The plugin's keybinding group.
  * @since 0.19.
  **/

src/spawn.c

@@ -705,10 +705,10 @@ static gboolean spawn_async_with_pipes(const gchar *working_directory, const gch
  *
  *  If a @a child_pid is passed, it's your responsibility to invoke @c g_spawn_close_pid().
  *
- *  @param working_directory child's current working directory, or @c NULL.
- *  @param command_line child program and arguments, or @c NULL.
- *  @param argv child's argument vector, or @c NULL.
- *  @param envp child's environment, or @c NULL.
+ *  @param working_directory @nullable child's current working directory, or @c NULL.
+ *  @param command_line @nullable child program and arguments, or @c NULL.
+ *  @param argv @nullable child's argument vector, or @c NULL.
+ *  @param envp @nullable child's environment, or @c NULL.
  *  @param child_pid @out @optional return location for child process ID, or @c NULL.
  *  @param error return location for error.
  *
@@ -978,20 +978,20 @@ static void spawn_watch_cb(GPid pid, gint status, gpointer data)
  *
  *  The @a child_pid will be closed automatically, after @a exit_cb is invoked.
  *
- *  @param working_directory child's current working directory, or @c NULL.
- *  @param command_line child program and arguments, or @c NULL.
- *  @param argv child's argument vector, or @c NULL.
- *  @param envp child's environment, or @c NULL.
+ *  @param working_directory @nullable child's current working directory, or @c NULL.
+ *  @param command_line @nullable child program and arguments, or @c NULL.
+ *  @param argv @nullable child's argument vector, or @c NULL.
+ *  @param envp @nullable child's environment, or @c NULL.
  *  @param spawn_flags flags from SpawnFlags.
- *  @param stdin_cb callback to send data to childs's stdin, or @c NULL.
+ *  @param stdin_cb @nullable callback to send data to childs's stdin, or @c NULL.
  *  @param stdin_data data to pass to @a stdin_cb.
- *  @param stdout_cb callback to receive child's stdout, or @c NULL.
+ *  @param stdout_cb @nullable callback to receive child's stdout, or @c NULL.
  *  @param stdout_data data to pass to @a stdout_cb.
  *  @param stdout_max_length maximum data length to pass to stdout_cb, @c 0 = default.
- *  @param stderr_cb callback to receive child's stderr, or @c NULL.
+ *  @param stderr_cb @nullable callback to receive child's stderr, or @c NULL.
  *  @param stderr_data data to pass to @a stderr_cb.
  *  @param stderr_max_length maximum data length to pass to stderr_cb, @c 0 = default.
- *  @param exit_cb callback to invoke when the child exits, or @c NULL.
+ *  @param exit_cb @nullable callback to invoke when the child exits, or @c NULL.
  *  @param exit_data data to pass to @a exit_cb.
  *  @param child_pid @out @optional return location for child process ID, or @c NULL.
  *  @param error return location for error.
@@ -1183,13 +1183,13 @@ static void spawn_get_exit_status_cb(G_GNUC_UNUSED GPid pid, gint status, gpoint
  *  All output from the child, including the nul characters, is stored in @a stdout_data and
  *  @a stderr_data (if non-NULL). Any existing data in these strings will be erased.
  *
- *  @param working_directory child's current working directory, or @c NULL.
- *  @param command_line child program and arguments, or @c NULL.
- *  @param argv child's argument vector, or @c NULL.
- *  @param envp child's environment, or @c NULL.
- *  @param stdin_data data to send to childs's stdin, or @c NULL.
- *  @param stdout_data GString location to receive the child's stdout, or NULL.
- *  @param stderr_data GString location to receive the child's stderr, or NULL.
+ *  @param working_directory @nullable child's current working directory, or @c NULL.
+ *  @param command_line @nullable child program and arguments, or @c NULL.
+ *  @param argv @nullable child's argument vector, or @c NULL.
+ *  @param envp @nullable child's environment, or @c NULL.
+ *  @param stdin_data @nullable data to send to childs's stdin, or @c NULL.
+ *  @param stdout_data @nullable GString location to receive the child's stdout, or @c NULL.
+ *  @param stderr_data @nullable GString location to receive the child's stderr, or @c NULL.
  *  @param exit_status @out @optional return location for the child exit code, or @c NULL.
  *  @param error return location for error.
  *

src/stash.c

@@ -495,7 +495,7 @@ void stash_group_add_integer(StashGroup *group, gint *setting,
  * @param group .
  * @param setting Address of setting variable.
  * @param key_name Name for key in a @c GKeyFile.
- * @param default_value String to copy if the key doesn't exist when loading, or @c NULL. */
+ * @param default_value @nullable String to copy if the key doesn't exist when loading, or @c NULL. */
 GEANY_API_SYMBOL
 void stash_group_add_string(StashGroup *group, gchar **setting,
 		const gchar *key_name, const gchar *default_value)