From 3b38cbc64da7d47329ba52a3ac7dc0a01511fe97 Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Mon, 10 Aug 2015 16:51:56 +0200 Subject: [PATCH 1/5] doxygen: do not sort elements alphabetically Sorting struct members alphabetically is harmful when generating code out of doxygen xml output, because the generated code does not match the original. Instead, do not sort. Order will be by appearance. Generated structs match the original. --- doc/Doxyfile.in | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 12098d1a54..c75a4eebba 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -556,7 +556,7 @@ INLINE_INFO = NO # name. If set to NO the members will appear in declaration order. # The default value is: YES. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member @@ -564,7 +564,7 @@ SORT_MEMBER_DOCS = YES # this will also influence the order of the classes in the class list. # The default value is: NO. -SORT_BRIEF_DOCS = YES +SORT_BRIEF_DOCS = NO # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the # (brief and detailed) documentation of class members so that constructors and From 5e43a9e04e43f0c26cee0b9edd1b776becb3d8b5 Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Mon, 10 Aug 2015 16:54:45 +0200 Subject: [PATCH 2/5] doxygen: generate xml too in preparation for gtkdoc generation A script will use the xml to generate a gtkdoc'ized header of the plugin API. The xml files are also installed so that external users can use the xml that corresponds to the installed version of Geany. --- doc/Doxyfile.in | 2 +- doc/Makefile.am | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index c75a4eebba..f817b96d48 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -1866,7 +1866,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/doc/Makefile.am b/doc/Makefile.am index a348cc9c23..064e3c87b5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -106,7 +106,7 @@ all-local: Doxyfile.stamp clean-local: clean-api-docs-local clean-api-docs-local: - -rm -rf reference/ Doxyfile.stamp doxygen_* + -rm -rf reference/ xml/ Doxyfile.stamp doxygen_* endif @@ -114,15 +114,18 @@ uninstall-local: rm -f $(DOCDIR)/html/index.html rm -f $(DOCDIR)/manual.txt rm -f $(DOCDIR)/ScintillaLicense.txt + rm -f $(DOCDIR)/xml/* # manually install some files under another name install-data-local: if INSTALL_HTML_DOCS $(mkinstalldirs) $(DOCDIR)/html + $(mkinstalldirs) $(DOCDIR)/xml # as we don't install with the automated mechanism so we can rename the file, # we need to find the source file in the right location (either builddir or srcdir) dir=$(builddir); test -f "$$dir/geany.html" || dir=$(srcdir); \ $(INSTALL_DATA) "$$dir/geany.html" $(DOCDIR)/html/index.html + $(INSTALL_DATA) -t $(DOCDIR)/xml xml/* endif $(mkinstalldirs) $(DOCDIR) $(INSTALL_DATA) $(srcdir)/geany.txt $(DOCDIR)/manual.txt From 37a9ebbb226731ce20e027c10cafb107ae0b396b Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Wed, 16 Sep 2015 17:02:18 +0200 Subject: [PATCH 3/5] plugin api: convert TMSourceFile to GBoxed internally Because the tm_source_file_new() is an exported API, it has to be at least a boxed type to be useable for gobject introsection. The obligatory tm_source_file_dup() is not exported (doesn't have to). --- tagmanager/src/tm_source_file.c | 37 +++++++++++++++++++++++++++++---- tagmanager/src/tm_source_file.h | 3 +++ tagmanager/src/tm_tag.c | 6 ++---- 3 files changed, 38 insertions(+), 8 deletions(-) diff --git a/tagmanager/src/tm_source_file.c b/tagmanager/src/tm_source_file.c index 2dbdaa34d0..778fc86a8c 100644 --- a/tagmanager/src/tm_source_file.c +++ b/tagmanager/src/tm_source_file.c @@ -170,7 +170,7 @@ static gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_ source_file->short_name = source_file->file_name; } - source_file->tags_array = g_ptr_array_new(); + source_file->tags_array = g_ptr_array_new_with_free_func((GDestroyNotify) tm_tag_unref); if (NULL == LanguageTable) { @@ -199,15 +199,27 @@ static gboolean tm_source_file_init(TMSourceFile *source_file, const char *file_ GEANY_API_SYMBOL TMSourceFile *tm_source_file_new(const char *file_name, const char *name) { - TMSourceFile *source_file = g_new(TMSourceFile, 1); + TMSourceFile *source_file = g_slice_new(TMSourceFile); if (TRUE != tm_source_file_init(source_file, file_name, name)) { - g_free(source_file); + g_slice_free(TMSourceFile, source_file); return NULL; } return source_file; } + +TMSourceFile *tm_source_file_dup(TMSourceFile *src) +{ + TMSourceFile *source_file = g_slice_dup(TMSourceFile, src); + source_file->lang = src->lang; + source_file->file_name = g_strdup(src->file_name); + source_file->short_name = source_file->file_name; + source_file->short_name += src->short_name - src->file_name; + source_file->tags_array = g_ptr_array_ref(src->tags_array); + return source_file; +} + /* Destroys the contents of the source file. Note that the tags are owned by the source file and are also destroyed when the source file is destroyed. If pointers to these tags are used elsewhere, then those tag arrays should be rebuilt. @@ -233,8 +245,25 @@ void tm_source_file_free(TMSourceFile *source_file) if (NULL != source_file) { tm_source_file_destroy(source_file); - g_free(source_file); + g_slice_free(TMSourceFile, source_file); + } +} + +/** Gets the GBoxed-derived GType for TMSourceFile + * + * @return TMSourceFile type . */ +GEANY_API_SYMBOL +GType tm_source_file_get_type(void) +{ + static volatile gsize type = 0; + if (g_once_init_enter(&type)) + { + GType g_type = g_boxed_type_register_static(g_intern_static_string("TMSourceFile"), + (GBoxedCopyFunc) tm_source_file_dup, + (GBoxedFreeFunc) tm_source_file_free); + g_once_init_leave(&type, g_type); } + return type; } /* Parses the text-buffer or source file and regenarates the tags. diff --git a/tagmanager/src/tm_source_file.h b/tagmanager/src/tm_source_file.h index 173b14a111..f2bdf4b1c9 100644 --- a/tagmanager/src/tm_source_file.h +++ b/tagmanager/src/tm_source_file.h @@ -12,6 +12,7 @@ #include #include +#include #ifndef LIBCTAGS_DEFINED typedef int langType; @@ -44,6 +45,8 @@ typedef struct GPtrArray *tags_array; /**< Sorted tag array obtained by parsing the object */ } TMSourceFile; +GType tm_source_file_get_type(void); + TMSourceFile *tm_source_file_new(const char *file_name, const char *name); void tm_source_file_free(TMSourceFile *source_file); diff --git a/tagmanager/src/tm_tag.c b/tagmanager/src/tm_tag.c index 1773e23f22..a03b918998 100644 --- a/tagmanager/src/tm_tag.c +++ b/tagmanager/src/tm_tag.c @@ -1044,16 +1044,14 @@ void tm_tags_array_free(GPtrArray *tags_array, gboolean free_all) { if (tags_array) { - guint i; - for (i = 0; i < tags_array->len; ++i) - tm_tag_unref(tags_array->pdata[i]); if (free_all) - g_ptr_array_free(tags_array, TRUE); + g_ptr_array_unref(tags_array); else g_ptr_array_set_size(tags_array, 0); } } + /* copy/pasted bsearch() from libc extended with user_data for comparison function * and using glib types */ static gpointer binary_search(gpointer key, gpointer base, size_t nmemb, From c3d269b6a2d0163c6fd53f7a94c35b585912d2b3 Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Wed, 16 Sep 2015 22:42:14 +0200 Subject: [PATCH 4/5] plugin api: convert StashGroup to GBoxed internally Because the stash_group_new() is an exported API, it has to be at least a boxed type to be useable for gobject introsection. The obligatory stash_group_dup() is not exported (doesn't have to). --- src/stash.c | 51 +++++++++++++++++++++++++++++++++++++++------------ src/stash.h | 1 + 2 files changed, 40 insertions(+), 12 deletions(-) diff --git a/src/stash.c b/src/stash.c index d4a5b698d8..3790157f29 100644 --- a/src/stash.c +++ b/src/stash.c @@ -347,21 +347,41 @@ gint stash_group_save_to_file(StashGroup *group, const gchar *filename, } +static void free_stash_pref(StashPref *entry) +{ + if (entry->widget_type == GTK_TYPE_RADIO_BUTTON) + { + g_free(entry->extra.radio_buttons); + } + g_slice_free(StashPref, entry); +} + + /** Creates a new group. * @param name Name used for @c GKeyFile group. * @return Group. */ GEANY_API_SYMBOL StashGroup *stash_group_new(const gchar *name) { - StashGroup *group = g_new0(StashGroup, 1); + StashGroup *group = g_slice_new0(StashGroup); group->name = name; - group->entries = g_ptr_array_new(); + group->entries = g_ptr_array_new_with_free_func((GDestroyNotify) free_stash_pref); group->use_defaults = TRUE; return group; } +StashGroup *stash_group_dup(StashGroup *src) +{ + StashGroup *group = g_slice_dup(StashGroup, src); + + group->entries = g_ptr_array_ref(src->entries); + + return group; +} + + /** Frees the memory allocated for setting values in a group. * Useful e.g. to avoid freeing strings individually. * @note This is *not* called by stash_group_free(). @@ -391,19 +411,26 @@ void stash_group_free_settings(StashGroup *group) GEANY_API_SYMBOL void stash_group_free(StashGroup *group) { - StashPref *entry; - guint i; + g_ptr_array_unref(group->entries); + g_slice_free(StashGroup, group); +} - foreach_ptr_array(entry, i, group->entries) + +/** Gets the GBoxed-derived GType for StashGroup + * + * @return StashGroup type . */ +GEANY_API_SYMBOL +GType stash_group_get_type(void) +{ + static volatile gsize type = 0; + if (g_once_init_enter(&type)) { - if (entry->widget_type == GTK_TYPE_RADIO_BUTTON) - { - g_free(entry->extra.radio_buttons); - } - g_slice_free(StashPref, entry); + GType g_type = g_boxed_type_register_static(g_intern_static_string("StashGroup"), + (GBoxedCopyFunc) stash_group_dup, + (GBoxedFreeFunc) stash_group_free); + g_once_init_leave(&type, g_type); } - g_ptr_array_free(group->entries, TRUE); - g_free(group); + return type; } diff --git a/src/stash.h b/src/stash.h index 5e44674266..e92563656d 100644 --- a/src/stash.h +++ b/src/stash.h @@ -33,6 +33,7 @@ typedef struct StashGroup StashGroup; * stash_group_display() and stash_group_update(). */ typedef gconstpointer StashWidgetID; +GType stash_group_get_type(void); StashGroup *stash_group_new(const gchar *name); From 15d2d6ceb7570a83cc6c44a69de0c7fc81766730 Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Wed, 16 Sep 2015 22:52:23 +0200 Subject: [PATCH 5/5] doxygen: various doxygen-related fixes in preparation for gtkdoc generation --- doc/Doxyfile.in | 6 ++++++ doc/pluginsymbols.c | 18 +++++++++++------- src/build.h | 33 ++++++++++++++++++--------------- src/document.c | 18 +++++++++--------- src/editor.c | 2 +- src/editor.h | 9 +++++---- src/encodings.h | 1 + src/filetypes.c | 19 +++++++++++++------ src/filetypes.h | 14 +++++++++++--- src/keybindings.c | 2 +- src/plugindata.h | 4 ++-- src/pluginutils.c | 10 ++++++++-- src/spawn.c | 1 + src/stash.c | 2 +- src/ui_utils.c | 29 +++++++++++++++++++---------- src/utils.c | 15 ++++++++------- tagmanager/src/tm_workspace.c | 4 ++-- 17 files changed, 117 insertions(+), 70 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index f817b96d48..ba8f7164b6 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -249,6 +249,12 @@ ALIASES = "signal=- @ref " \ "signals=@b Signals: " \ "endsignals= " +ALIASES += "transfer{1}=\a \xmlonly \1\endxmlonly \htmlonly (transfer: \1) \endhtmlonly" +ALIASES += "elementtype{1}=\a \xmlonly \1\endxmlonly \htmlonly (element-type: \1) \endhtmlonly" +ALIASES += "scope{1}=\a \xmlonly \1\endxmlonly \htmlonly (element-type: \1) \endhtmlonly" +ALIASES += "skip=\a \xmlonly \endxmlonly" + + # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" # will allow you to use the command class in the itcl::class meaning. diff --git a/doc/pluginsymbols.c b/doc/pluginsymbols.c index b0fd48a1fc..bbc8471135 100644 --- a/doc/pluginsymbols.c +++ b/doc/pluginsymbols.c @@ -37,8 +37,10 @@ */ /** Use the PLUGIN_VERSION_CHECK() macro instead. Required by Geany. - * @return . */ -gint plugin_version_check(gint); + * + * @param abi ABI version Geany was compiled with + * @return The API version the plugin was compiled with, or -1 if the plugin is incompatible. */ +gint plugin_version_check(gint abi); /** Use the PLUGIN_SET_INFO() macro to define it. Required by Geany. * This function is called before the plugin is initialized, so Geany @@ -46,8 +48,8 @@ gint plugin_version_check(gint); * @param info The data struct which should be initialized by this function. */ void plugin_set_info(PluginInfo *info); -/** @deprecated Use @ref GeanyPlugin.info instead. - * Basic information about a plugin, which is set in plugin_set_info(). */ +/** Basic information about a plugin, which is set in plugin_set_info(). + * @deprecated Use @ref GeanyPlugin.info instead.*/ const PluginInfo *plugin_info; /** Basic information for the plugin and identification. */ @@ -64,8 +66,8 @@ const GeanyData *geany_data; * This is equivalent of @c geany_functions->p_document->document_new_file(NULL, NULL, NULL); */ const GeanyFunctions *geany_functions; -/** @deprecated Use @ref ui_add_document_sensitive() instead. - * Plugin owned fields, including flags. */ +/** Plugin owned fields, including flags. + * @deprecated Use @ref ui_add_document_sensitive() instead.*/ PluginFields *plugin_fields; /** An array for connecting GeanyObject events, which should be terminated with @@ -85,7 +87,9 @@ KeyBindingGroup *plugin_key_group; * @param dialog The plugin preferences dialog widget - this should only be used to * connect the @c "response" signal. If settings should be read from the dialog, the * response will be either @c GTK_RESPONSE_OK or @c GTK_RESPONSE_APPLY. - * @return A container widget holding preference widgets. + * + * @return @transfer{floating} A container widget holding preference widgets. + * * @note Using @link stash.h Stash @endlink can make implementing preferences easier. * @see plugin_configure_single(). */ GtkWidget *plugin_configure(GtkDialog *dialog); diff --git a/src/build.h b/src/build.h index a52e0eccbe..d1f7ea4c39 100644 --- a/src/build.h +++ b/src/build.h @@ -55,10 +55,10 @@ typedef enum /** The entries of a command for a menu item */ typedef enum GeanyBuildCmdEntries { - GEANY_BC_LABEL, /* *< The menu item label, _ marks mnemonic */ - GEANY_BC_COMMAND, /* *< The command to run. */ - GEANY_BC_WORKING_DIR, /* *< The directory to run in */ - GEANY_BC_CMDENTRIES_COUNT /* *< Count of entries */ + GEANY_BC_LABEL, /**< The menu item label, _ marks mnemonic */ + GEANY_BC_COMMAND, /**< The command to run. */ + GEANY_BC_WORKING_DIR, /**< The directory to run in */ + GEANY_BC_CMDENTRIES_COUNT /**< Count of entries */ } GeanyBuildCmdEntries; void build_activate_menu_item(const GeanyBuildGroup grp, const guint cmd); @@ -73,6 +73,20 @@ void build_set_menu_item(const GeanyBuildSource src, const GeanyBuildGroup grp, guint build_get_group_count(const GeanyBuildGroup grp); +/** Structure describing a single build + * + * GeanyData has a pointer to a singleton instance of this that is updated whenever the + * user launches a build process */ +typedef struct GeanyBuildInfo +{ + GeanyBuildGroup grp; + guint cmd; + GPid pid; /* process id of the spawned process */ + gchar *dir; + guint file_type_id; + gchar *custom_target; + gint message_count; +} GeanyBuildInfo; #ifdef GEANY_PRIVATE @@ -135,17 +149,6 @@ enum GeanyBuildFixedMenuItems GBF_COUNT }; -typedef struct GeanyBuildInfo -{ - GeanyBuildGroup grp; - guint cmd; - GPid pid; /* process id of the spawned process */ - gchar *dir; - guint file_type_id; - gchar *custom_target; - gint message_count; -} GeanyBuildInfo; - extern GeanyBuildInfo build_info; /* * The command for a menu item. */ diff --git a/src/document.c b/src/document.c index c65f838172..ac1c678139 100644 --- a/src/document.c +++ b/src/document.c @@ -145,7 +145,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 The matching document, or @c NULL. + * @return @transfer{none} 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(). @@ -195,7 +195,7 @@ static gchar *get_real_path_from_utf8(const gchar *utf8_filename) * * @param utf8_filename The filename to search (in UTF-8 encoding). * - * @return The matching document, or @c NULL. + * @return @transfer{none} The matching document, or @c NULL. * @see document_find_by_real_path(). **/ GEANY_API_SYMBOL @@ -249,7 +249,7 @@ GeanyDocument *document_find_by_sci(ScintillaObject *sci) * Useful when the corresponding document may have been closed since the * ID was retrieved. * @param id The ID of the document to find - * @return @c NULL if the document is no longer open. + * @return @transfer{none} @c NULL if the document is no longer open. * * Example: * @code @@ -365,7 +365,7 @@ GeanyDocument *document_get_from_notebook_child(GtkWidget *page) * * @param page_num The notebook page number to search. * - * @return The corresponding document for the given notebook page, or @c NULL. + * @return @transfer{none} The corresponding document for the given notebook page, or @c NULL. **/ GEANY_API_SYMBOL GeanyDocument *document_get_from_page(guint page_num) @@ -384,7 +384,7 @@ GeanyDocument *document_get_from_page(guint page_num) /** * Finds the current document. * - * @return A pointer to the current document or @c NULL if there are no opened documents. + * @return @transfer{none} A pointer to the current document or @c NULL if there are no opened documents. **/ GEANY_API_SYMBOL GeanyDocument *document_get_current(void) @@ -829,7 +829,7 @@ GeanyDocument *document_new_file_if_non_open(void) * @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. * - * @return The new document. + * @return @transfer{none} The new document. **/ GEANY_API_SYMBOL GeanyDocument *document_new_file(const gchar *utf8_filename, GeanyFiletype *ft, const gchar *text) @@ -913,7 +913,7 @@ GeanyDocument *document_new_file(const gchar *utf8_filename, GeanyFiletype *ft, * @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. * - * @return The document opened or @c NULL. + * @return @transfer{none} The document opened or @c NULL. **/ GEANY_API_SYMBOL GeanyDocument *document_open_file(const gchar *locale_filename, gboolean readonly, @@ -1557,7 +1557,7 @@ void document_open_file_list(const gchar *data, gsize length) * Opens each file in the list @a filenames. * Internally, document_open_file() is called for every list item. * - * @param filenames A list of filenames to load, in locale encoding. + * @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. @@ -3286,7 +3286,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 The document, or @c NULL if @a idx is out of range. + * @return @transfer{none} The document, or @c NULL if @a idx is out of range. * * @since 0.16 */ diff --git a/src/editor.c b/src/editor.c index 13365883fd..fb736005d4 100644 --- a/src/editor.c +++ b/src/editor.c @@ -4871,7 +4871,7 @@ static ScintillaObject *create_new_sci(GeanyEditor *editor) /** Creates a new Scintilla @c GtkWidget based on the settings for @a editor. * @param editor Editor settings. - * @return The new widget. + * @return @transfer{floating} The new widget. * * @since 0.15 **/ diff --git a/src/editor.h b/src/editor.h index 39035285eb..9e8049f9cc 100644 --- a/src/editor.h +++ b/src/editor.h @@ -50,12 +50,13 @@ typedef enum } GeanyIndentType; +/** Auto indentation modes */ typedef enum { - GEANY_AUTOINDENT_NONE = 0, - GEANY_AUTOINDENT_BASIC, - GEANY_AUTOINDENT_CURRENTCHARS, - GEANY_AUTOINDENT_MATCHBRACES + GEANY_AUTOINDENT_NONE = 0, /**< Autoindent Disabled */ + GEANY_AUTOINDENT_BASIC, /**< Very basic mode */ + GEANY_AUTOINDENT_CURRENTCHARS, /**< Autoindent based on the first char of the previous line */ + GEANY_AUTOINDENT_MATCHBRACES /**< Autoindent based on the position of the opening brace */ } GeanyAutoIndent; diff --git a/src/encodings.h b/src/encodings.h index 8beb79c94f..976ec0e0b1 100644 --- a/src/encodings.h +++ b/src/encodings.h @@ -40,6 +40,7 @@ G_BEGIN_DECLS +/** Internally used member for grouping in GeanyEncoding */ typedef enum { NONE = 0, diff --git a/src/filetypes.c b/src/filetypes.c index 5cfe4bc8d9..3995663914 100644 --- a/src/filetypes.c +++ b/src/filetypes.c @@ -55,7 +55,14 @@ #define GEANY_FILETYPE_SEARCH_LINES 2 /* lines of file to search for filetype */ -GPtrArray *filetypes_array = NULL; /* Dynamic array of filetype pointers */ +/** Dynamic array of filetype pointers + * + * List the list is dynamically expanded for custom filetypes filetypes so don't expect + * the list of known filetypes to be a constant. + * + * @elementtype{GeanyFiletype} + * */ +GPtrArray *filetypes_array = NULL; static GHashTable *filetypes_hash = NULL; /* Hash of filetype pointers based on name keys */ @@ -233,7 +240,7 @@ static gint cmp_filetype(gconstpointer pft1, gconstpointer pft2, gpointer data) /** Gets a list of filetype pointers sorted by name. * The list does not change on subsequent calls. - * @return The list - do not free. + * @return @elementtype{GeanyFiletype} @transfer{none} The list - do not free. * @see filetypes_by_title. */ GEANY_API_SYMBOL const GSList *filetypes_get_sorted_by_name(void) @@ -764,8 +771,8 @@ GeanyFiletype *filetypes_detect_from_document(GeanyDocument *doc) * * @param utf8_filename The filename in UTF-8 encoding. * - * @return The detected filetype for @a utf8_filename or @c filetypes[GEANY_FILETYPES_NONE] - * if it could not be detected. + * @return @transfer{none} The detected filetype for @a utf8_filename or + * @c filetypes[GEANY_FILETYPES_NONE] if it could not be detected. **/ GEANY_API_SYMBOL GeanyFiletype *filetypes_detect_from_file(const gchar *utf8_filename) @@ -1246,7 +1253,7 @@ gboolean filetype_has_tags(GeanyFiletype *ft) /** Finds a filetype pointer from its @a name field. * @param name Filetype name. - * @return The filetype found, or @c NULL. + * @return @transfer{none} The filetype found, or @c NULL. * * @since 0.15 **/ @@ -1492,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 The filetype, or @c NULL if @a idx is out of range. + * @return @transfer{none} The filetype, or @c NULL if @a idx is out of range. * * @since 0.16 */ diff --git a/src/filetypes.h b/src/filetypes.h index b9591a1401..c25c8e22bf 100644 --- a/src/filetypes.h +++ b/src/filetypes.h @@ -38,7 +38,10 @@ G_BEGIN_DECLS /* Forward-declared to avoid including document.h since it includes this header */ struct GeanyDocument; -/* Do not change the order, only append. */ +/** IDs of known filetypes + * + * @ref filetypes_array will contain an item for each. Use filetypes_array->len to + * determine the number of known filetypes at runtime */ typedef enum { GEANY_FILETYPES_NONE = 0, /* first filetype is always None & must be 0 */ @@ -106,8 +109,13 @@ typedef enum /* ^ append items here */ GEANY_MAX_BUILT_IN_FILETYPES /* Don't use this, use filetypes_array->len instead */ } -filetype_id; +GeanyFiletypeID; + +#define filetype_id GeanyFiletypeID +/** Filetype categories + * + * These are used to provide submenus for each category in the GUI */ typedef enum { GEANY_FILETYPE_GROUP_NONE, @@ -128,7 +136,7 @@ GeanyFiletypeGroupID; /** Represents a filetype. */ typedef struct GeanyFiletype { - filetype_id id; /**< Index in @c filetypes_array. */ + GeanyFiletypeID id; /**< Index in @c filetypes_array. */ /** Represents the langType of tagmanager (see the table * in tagmanager/parsers.h), -1 represents all, -2 none. */ langType lang; diff --git a/src/keybindings.c b/src/keybindings.c index 8913c572f6..3469db5799 100644 --- a/src/keybindings.c +++ b/src/keybindings.c @@ -158,7 +158,7 @@ GeanyKeyBinding *keybindings_get_item(GeanyKeyGroup *group, gsize key_id) * @param key_id Keybinding index for the group. * @param callback 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 (Lower case) default key, e.g. @c GDK_j, but usually 0 for unset. + * @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 diff --git a/src/plugindata.h b/src/plugindata.h index da94300437..98c2417ea9 100644 --- a/src/plugindata.h +++ b/src/plugindata.h @@ -222,8 +222,8 @@ typedef struct GeanyData { struct GeanyApp *app; /**< Geany application data fields */ struct GeanyMainWidgets *main_widgets; /**< Important widgets in the main window */ - GPtrArray *documents_array; /**< See document.h#documents_array. */ - GPtrArray *filetypes_array; /**< Dynamic array of GeanyFiletype pointers */ + GPtrArray *documents_array; /**< See document.h#documents_array. @elementtype{GeanyDocument} */ + GPtrArray *filetypes_array; /**< Dynamic array of GeanyFiletype pointers. @elementtype{GeanyFiletype} */ struct GeanyPrefs *prefs; /**< General settings */ struct GeanyInterfacePrefs *interface_prefs; /**< Interface settings */ struct GeanyToolbarPrefs *toolbar_prefs; /**< Toolbar settings */ diff --git a/src/pluginutils.c b/src/pluginutils.c index e48b4c1ade..19160ad99e 100644 --- a/src/pluginutils.c +++ b/src/pluginutils.c @@ -128,7 +128,9 @@ void plugin_module_make_resident(GeanyPlugin *plugin) * object has been destroyed), and disconnect yourself or not as appropriate. * @note Since version 1.25 (API >= 218), the object lifetime is watched and so the above * restriction does not apply. However, for objects destroyed by the plugin, - * @c g_signal_connect() is safe and has lower overhead. */ + * @c g_signal_connect() is safe and has lower overhead. + * @skip + **/ GEANY_API_SYMBOL void plugin_signal_connect(GeanyPlugin *plugin, GObject *object, const gchar *signal_name, gboolean after, @@ -241,6 +243,7 @@ static guint plugin_source_add(GeanyPlugin *plugin, GSource *source, GSourceFunc * * @see g_timeout_add() * @since 0.21, plugin API 205. + * @skip */ GEANY_API_SYMBOL guint plugin_timeout_add(GeanyPlugin *plugin, guint interval, GSourceFunc function, gpointer data) @@ -261,6 +264,7 @@ guint plugin_timeout_add(GeanyPlugin *plugin, guint interval, GSourceFunc functi * * @see g_timeout_add_seconds() * @since 0.21, plugin API 205. + * @skip */ GEANY_API_SYMBOL guint plugin_timeout_add_seconds(GeanyPlugin *plugin, guint interval, GSourceFunc function, @@ -281,6 +285,7 @@ guint plugin_timeout_add_seconds(GeanyPlugin *plugin, guint interval, GSourceFun * * @see g_idle_add() * @since 0.21, plugin API 205. + * @skip */ GEANY_API_SYMBOL guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data) @@ -296,7 +301,8 @@ guint plugin_idle_add(GeanyPlugin *plugin, GSourceFunc function, gpointer data) * @param count Number of keybindings for the group. * @param callback Group callback, or @c NULL if you only want individual keybinding callbacks. * @return The plugin's keybinding group. - * @since 0.19. */ + * @since 0.19. + * @skip */ GEANY_API_SYMBOL GeanyKeyGroup *plugin_set_key_group(GeanyPlugin *plugin, const gchar *section_name, gsize count, GeanyKeyGroupCallback callback) diff --git a/src/spawn.c b/src/spawn.c index e72f2fb9de..3012a33824 100644 --- a/src/spawn.c +++ b/src/spawn.c @@ -995,6 +995,7 @@ static void spawn_watch_cb(GPid pid, gint status, gpointer data) * @return @c TRUE on success, @c FALSE on error. * * @since 1.25 + * @skip **/ GEANY_API_SYMBOL gboolean spawn_with_callbacks(const gchar *working_directory, const gchar *command_line, diff --git a/src/stash.c b/src/stash.c index 3790157f29..b83720bc79 100644 --- a/src/stash.c +++ b/src/stash.c @@ -359,7 +359,7 @@ static void free_stash_pref(StashPref *entry) /** Creates a new group. * @param name Name used for @c GKeyFile group. - * @return Group. */ + * @return @transfer{full} Group. */ GEANY_API_SYMBOL StashGroup *stash_group_new(const gchar *name) { diff --git a/src/ui_utils.c b/src/ui_utils.c index 7472608e4f..89c51de61a 100644 --- a/src/ui_utils.c +++ b/src/ui_utils.c @@ -1461,7 +1461,10 @@ void ui_update_view_editor_menu_items(void) /** Creates a GNOME HIG-style frame (with no border and indented child alignment). * @param label_text The label text. * @param alignment An address to store the alignment widget pointer. - * @return The frame widget, setting the alignment container for packing child widgets. */ + * + * @return @transfer{floating} The frame widget, setting the alignment container for + * packing child widgets. + **/ GEANY_API_SYMBOL GtkWidget *ui_frame_new_with_alignment(const gchar *label_text, GtkWidget **alignment) { @@ -1484,7 +1487,8 @@ GtkWidget *ui_frame_new_with_alignment(const gchar *label_text, GtkWidget **alig /** Makes a fixed border for dialogs without increasing the button box border. * @param dialog The parent container for the @c GtkVBox. - * @return The packed @c GtkVBox. */ + * + * @return @transfer{none} The packed @c GtkVBox. */ GEANY_API_SYMBOL GtkWidget *ui_dialog_vbox_new(GtkDialog *dialog) { @@ -1535,7 +1539,8 @@ void ui_dialog_set_primary_button_order(GtkDialog *dialog, gint response, ...) * @c gtk_button_new_from_stock(). * @param stock_id A @c GTK_STOCK_NAME string. * @param text Button label text, can include mnemonics. - * @return The new @c GtkButton. + * + * @return @transfer{floating} The new @c GtkButton. */ GEANY_API_SYMBOL GtkWidget *ui_button_new_with_image(const gchar *stock_id, const gchar *text) @@ -1554,7 +1559,7 @@ GtkWidget *ui_button_new_with_image(const gchar *stock_id, const gchar *text) /** Creates a @c GtkImageMenuItem with a stock image and a custom label. * @param stock_id Stock image ID, e.g. @c GTK_STOCK_OPEN. * @param label Menu item label, can include mnemonics. - * @return The new @c GtkImageMenuItem. + * @return @transfer{floating} The new @c GtkImageMenuItem. * * @since 0.16 */ @@ -1898,7 +1903,8 @@ void ui_widget_modify_font_from_string(GtkWidget *widget, const gchar *str) * @param action The mode of the file chooser. * @param entry Can be an unpacked @c GtkEntry, or the child of an unpacked widget, * such as @c GtkComboBoxEntry. - * @return The @c GtkHBox. + * + * @return @transfer{floating} The @c GtkHBox. */ /* @see ui_setup_open_button_callback(). */ GEANY_API_SYMBOL @@ -2651,7 +2657,8 @@ void ui_widget_set_tooltip_text(GtkWidget *widget, const gchar *text) * you want returned. * @param widget Widget with the @a widget_name property set. * @param widget_name Name to lookup. - * @return The widget found. + * + * @return @transfer{none} The widget found. * @see ui_hookup_widget(). * * @since 0.16 @@ -2839,10 +2846,11 @@ GtkWidget *ui_label_new_bold(const gchar *text) /** Adds a list of document items to @a menu. * @param menu Menu. * @param active Which document to highlight, or @c NULL. - * @param callback is used for each menu item's @c "activate" signal and will be passed - * the corresponding document pointer as @c user_data. + * @param callback is used for each menu item's @c "activate" signal and will be + * passed the corresponding document pointer as @c user_data. * @warning You should check @c doc->is_valid in the callback. - * @since 0.19 */ + * @since 0.19 + * @skip */ GEANY_API_SYMBOL void ui_menu_add_document_items(GtkMenu *menu, GeanyDocument *active, GCallback callback) { @@ -2863,7 +2871,8 @@ void ui_menu_add_document_items(GtkMenu *menu, GeanyDocument *active, GCallback * the corresponding document pointer as @c user_data. * @param compare_func is used to sort the list. Might be @c NULL to not sort the list. * @warning You should check @c doc->is_valid in the callback. - * @since 0.21 */ + * @since 0.21 + * @skip */ GEANY_API_SYMBOL void ui_menu_add_document_items_sorted(GtkMenu *menu, GeanyDocument *active, GCallback callback, GCompareFunc compare_func) diff --git a/src/utils.c b/src/utils.c index b6ad701345..42da1fb348 100644 --- a/src/utils.c +++ b/src/utils.c @@ -1405,8 +1405,8 @@ gint utils_mkdir(const gchar *path, gboolean create_parent_dirs) * @param sort Whether to sort alphabetically (UTF-8 safe). * @param error The location for storing a possible error, or @c NULL. * - * @return A newly allocated list or @c NULL if no files were found. The list and its data should be - * freed when no longer needed. + * @return @elementtype{filename} @transfer{full} A newly allocated list or @c NULL if + * no files were found. The list and its data should be freed when no longer needed. * @see utils_get_file_list(). **/ GEANY_API_SYMBOL @@ -1450,8 +1450,8 @@ GSList *utils_get_file_list_full(const gchar *path, gboolean full_path, gboolean * unless @c NULL. * @param error The location for storing a possible error, or @c NULL. * - * @return A newly allocated list or @c NULL if no files were found. The list and its data should be - * freed when no longer needed. + * @return @elementtype{filename} @transfer{full} A newly allocated list or @c NULL + * if no files were found. The list and its data should be freed when no longer needed. * @see utils_get_file_list_full(). **/ GEANY_API_SYMBOL @@ -1651,7 +1651,7 @@ const gchar *utils_get_default_dir_utf8(void) * @param argv The child's argument vector. * @param env The child's environment, or @a NULL to inherit parent's. * @param flags Ignored. - * @param child_setup Ignored. + * @param child_setup @skip Ignored. * @param user_data Ignored. * @param std_out The return location for child output, or @a NULL. * @param std_err The return location for child error messages, or @a NULL. @@ -1686,7 +1686,7 @@ gboolean utils_spawn_sync(const gchar *dir, gchar **argv, gchar **env, GSpawnFla * @param argv The child's argument vector. * @param env The child's environment, or @a NULL to inherit parent's. * @param flags Ignored. - * @param child_setup Ignored. + * @param child_setup @skip Ignored. * @param user_data Ignored. * @param child_pid The return location for child process ID, or NULL. * @param error The return location for error or @a NULL. @@ -1955,11 +1955,12 @@ static gboolean str_in_array(const gchar **haystack, const gchar *needle) * * The argument list must be @c NULL-terminated. * + * * @param exclude_vars @c NULL-terminated array of variable names to exclude. * @param first_varname Name of the first variable to copy into the new array. * @param ... Key-value pairs of variable names and values, @c NULL-terminated. * - * @return The new environment array. + * @return @transfer{full} The new environment array. Use @c g_strfreev() to free it. **/ GEANY_API_SYMBOL gchar **utils_copy_environment(const gchar **exclude_vars, const gchar *first_varname, ...) diff --git a/tagmanager/src/tm_workspace.c b/tagmanager/src/tm_workspace.c index 5b345c23bf..6bcd3ab6a1 100644 --- a/tagmanager/src/tm_workspace.c +++ b/tagmanager/src/tm_workspace.c @@ -267,7 +267,7 @@ static void tm_workspace_update(void) /** Adds multiple source files to the workspace and updates the workspace tag arrays. This is more efficient than calling tm_workspace_add_source_file() and tm_workspace_update_source_file() separately for each of the files. - @param source_files The source files to be added to the workspace. + @param source_files @elementtype{TMSourceFile} The source files to be added to the workspace. */ GEANY_API_SYMBOL void tm_workspace_add_source_files(GPtrArray *source_files) @@ -292,7 +292,7 @@ void tm_workspace_add_source_files(GPtrArray *source_files) arrays. This is more efficient than calling tm_workspace_remove_source_file() separately for each of the files. To completely free the TMSourceFile pointers call tm_source_file_free() on each of them. - @param source_files The source files to be removed from the workspace. + @param source_files @elementtype{TMSourceFile} The source files to be removed from the workspace. */ GEANY_API_SYMBOL void tm_workspace_remove_source_files(GPtrArray *source_files)