From d3417b7b37d289fc2a7d985f54c5b8a5385f295e Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Tue, 23 Jan 2018 19:05:28 +0100 Subject: [PATCH 1/4] api: add non-variadic variants of msgwin_*_add to the API The variadic variants cannot be gobject-introspected, i.e. are not available in Peasy. In fact, msgwin_compiler_add_string() and msgwin_msg_add_string() already existed and have just been exported. msgwin_status_add_string() is new but msgwin_status_add() becaume a wrapper around it in the same fashion as the other two pairs. --- src/msgwindow.c | 59 +++++++++++++++++++++++++++++++++++++++---------- src/msgwindow.h | 7 +++--- 2 files changed, 50 insertions(+), 16 deletions(-) diff --git a/src/msgwindow.c b/src/msgwindow.c index 02e45234..a9e23e5b 100644 --- a/src/msgwindow.c +++ b/src/msgwindow.c @@ -334,7 +334,15 @@ void msgwin_compiler_add(gint msg_color, const gchar *format, ...) g_free(string); } - +/** + * Adds a new message in the compiler tab treeview in the messages window. + * + * @param msg_color A color to be used for the text. It must be an element of #MsgColors. + * @param msg Compiler message to be added. + * + * @since @todo + **/ +GEANY_API_SYMBOL void msgwin_compiler_add_string(gint msg_color, const gchar *msg) { GtkTreeIter iter; @@ -410,7 +418,19 @@ void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar * } -/* adds string to the msg treeview */ +/** + * Adds a new message in the messages tab treeview in the messages window. + * If @a line and @a doc are set, clicking on this line jumps into the + * file which is specified by @a doc into the line specified with @a line. + * + * @param msg_color A color to be used for the text. It must be an element of #MsgColors. + * @param line The document's line where the message belongs to. Set to @c -1 to ignore. + * @param doc The document. Set to @c NULL to ignore. + * @param string Message to be added. + * + * @since @todo + **/ +GEANY_API_SYMBOL void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const gchar *string) { GtkTreeIter iter; @@ -451,26 +471,20 @@ void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const * Logs a status message *without* setting the status bar. * (Use ui_set_statusbar() to display text on the statusbar) * - * @param format @c printf()-style format string. - * @param ... Arguments for the @c format string. + * @param string Status message to be logged. + * + * @since @todo **/ GEANY_API_SYMBOL -void msgwin_status_add(const gchar *format, ...) +void msgwin_status_add_string(const gchar *string) { GtkTreeIter iter; - gchar *string; gchar *statusmsg, *time_str; - va_list args; - - va_start(args, format); - string = g_strdup_vprintf(format, args); - va_end(args); /* add a timestamp to status messages */ time_str = utils_get_current_time_string(); statusmsg = g_strconcat(time_str, ": ", string, NULL); g_free(time_str); - g_free(string); /* add message to Status window */ gtk_list_store_append(msgwindow.store_status, &iter); @@ -488,6 +502,27 @@ void msgwin_status_add(const gchar *format, ...) } } +/** + * Logs a status message *without* setting the status bar. + * (Use ui_set_statusbar() to display text on the statusbar) + * + * @param format @c printf()-style format string. + * @param ... Arguments for the @c format string. + **/ +GEANY_API_SYMBOL +void msgwin_status_add(const gchar *format, ...) +{ + gchar *string; + va_list args; + + va_start(args, format); + string = g_strdup_vprintf(format, args); + va_end(args); + + msgwin_status_add_string(string); + g_free(string); +} + static void on_message_treeview_clear_activate(GtkMenuItem *menuitem, gpointer user_data) diff --git a/src/msgwindow.h b/src/msgwindow.h index dc5fc356..e7d76963 100644 --- a/src/msgwindow.h +++ b/src/msgwindow.h @@ -53,11 +53,14 @@ typedef enum void msgwin_status_add(const gchar *format, ...) G_GNUC_PRINTF (1, 2); +void msgwin_status_add_string(const gchar *msg); void msgwin_compiler_add(gint msg_color, const gchar *format, ...) G_GNUC_PRINTF (2, 3); +void msgwin_compiler_add_string(gint msg_color, const gchar *msg); void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar *format, ...) G_GNUC_PRINTF (4, 5); +void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const char *msg); void msgwin_clear_tab(gint tabnum); @@ -93,10 +96,6 @@ void msgwin_finalize(void); void msgwin_show_hide(gboolean show); -void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const gchar *string); - -void msgwin_compiler_add_string(gint msg_color, const gchar *msg); - void msgwin_show_hide_tabs(void); From cb179943ad8819e7c1bf9a8e359264cf87ee27f4 Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Tue, 23 Jan 2018 22:28:50 +0100 Subject: [PATCH 2/4] msgwin: beautify doxygen comments a bit --- src/msgwindow.c | 93 +++++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 42 deletions(-) diff --git a/src/msgwindow.c b/src/msgwindow.c index a9e23e5b..79bae392 100644 --- a/src/msgwindow.c +++ b/src/msgwindow.c @@ -106,9 +106,11 @@ void msgwin_show_hide_tabs(void) } -/** Sets the Messages path for opening any parsed filenames without absolute path - * from message lines. - * @param messages_dir The directory. **/ +/** + * Sets the Messages path for opening any parsed filenames without absolute path from message lines. + * + * @param messages_dir The directory. + **/ GEANY_API_SYMBOL void msgwin_set_messages_dir(const gchar *messages_dir) { @@ -315,11 +317,13 @@ static const GdkColor *get_color(gint msg_color) /** - * Adds a new message in the compiler tab treeview in the messages window. + * Adds a new message in the compiler tab treeview in the messages window. * - * @param msg_color A color to be used for the text. It must be an element of #MsgColors. - * @param format @c printf()-style format string. - * @param ... Arguments for the @c format string. + * @param msg_color A color to be used for the text. It must be an element of #MsgColors. + * @param format @c printf()-style format string. + * @param ... Arguments for the @c format string. + * + * @since 0.15 **/ GEANY_API_SYMBOL void msgwin_compiler_add(gint msg_color, const gchar *format, ...) @@ -335,12 +339,12 @@ void msgwin_compiler_add(gint msg_color, const gchar *format, ...) } /** - * Adds a new message in the compiler tab treeview in the messages window. + * Adds a new message in the compiler tab treeview in the messages window. * - * @param msg_color A color to be used for the text. It must be an element of #MsgColors. - * @param msg Compiler message to be added. + * @param msg_color A color to be used for the text. It must be an element of #MsgColors. + * @param msg Compiler message to be added. * - * @since @todo + * @since @todo **/ GEANY_API_SYMBOL void msgwin_compiler_add_string(gint msg_color, const gchar *msg) @@ -391,15 +395,16 @@ void msgwin_show_hide(gboolean show) /** - * Adds a new message in the messages tab treeview in the messages window. - * If @a line and @a doc are set, clicking on this line jumps into the file which is specified - * by @a doc into the line specified with @a line. + * Adds a new message in the messages tab treeview in the messages window. * - * @param msg_color A color to be used for the text. It must be an element of #MsgColors. - * @param line The document's line where the message belongs to. Set to @c -1 to ignore. - * @param doc The document. Set to @c NULL to ignore. - * @param format @c printf()-style format string. - * @param ... Arguments for the @c format string. + * If @a line and @a doc are set, clicking on this line jumps into the file + * which is specified by @a doc into the line specified with @a line. + * + * @param msg_color A color to be used for the text. It must be an element of #MsgColors. + * @param line The document's line where the message belongs to. Set to @c -1 to ignore. + * @param doc @nullable The document. Set to @c NULL to ignore. + * @param format @c printf()-style format string. + * @param ... Arguments for the @c format string. * * @since 0.15 **/ @@ -419,16 +424,17 @@ void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar * /** - * Adds a new message in the messages tab treeview in the messages window. - * If @a line and @a doc are set, clicking on this line jumps into the - * file which is specified by @a doc into the line specified with @a line. + * Adds a new message in the messages tab treeview in the messages window. * - * @param msg_color A color to be used for the text. It must be an element of #MsgColors. - * @param line The document's line where the message belongs to. Set to @c -1 to ignore. - * @param doc The document. Set to @c NULL to ignore. - * @param string Message to be added. + * If @a line and @a doc are set, clicking on this line jumps into the + * file which is specified by @a doc into the line specified with @a line. * - * @since @todo + * @param msg_color A color to be used for the text. It must be an element of #MsgColors. + * @param line The document's line where the message belongs to. Set to @c -1 to ignore. + * @param doc @nullable The document. Set to @c NULL to ignore. + * @param string Message to be added. + * + * @since @todo **/ GEANY_API_SYMBOL void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const gchar *string) @@ -468,12 +474,13 @@ void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const /** - * Logs a status message *without* setting the status bar. - * (Use ui_set_statusbar() to display text on the statusbar) + * Logs a status message *without* setting the status bar. * - * @param string Status message to be logged. + * Use @ref ui_set_statusbar() to display text on the statusbar. * - * @since @todo + * @param string Status message to be logged. + * + * @since @todo **/ GEANY_API_SYMBOL void msgwin_status_add_string(const gchar *string) @@ -503,11 +510,12 @@ void msgwin_status_add_string(const gchar *string) } /** - * Logs a status message *without* setting the status bar. - * (Use ui_set_statusbar() to display text on the statusbar) + * Logs a status message *without* setting the status bar. * - * @param format @c printf()-style format string. - * @param ... Arguments for the @c format string. + * Use @ref ui_set_statusbar() to display text on the statusbar. + * + * @param format @c printf()-style format string. + * @param ... Arguments for the @c format string. **/ GEANY_API_SYMBOL void msgwin_status_add(const gchar *format, ...) @@ -1272,12 +1280,13 @@ static gboolean on_msgwin_button_press_event(GtkWidget *widget, GdkEventButton * /** - * Switches to the given notebook tab of the messages window and shows the messages window - * if it was previously hidden and @a show is set to @c TRUE. + * Switches to the given notebook tab of the messages window. * - * @param tabnum An index of a tab in the messages window. Valid values are all elements of - * #MessageWindowTabNum. - * @param show Whether to show the messages window at all if it was hidden before. + * The messages window is shown if it was previously hidden and @a show is set to @c TRUE. + * + * @param tabnum An index of a tab in the messages window. Valid values are + * all elements of #MessageWindowTabNum. + * @param show Whether to show the messages window at all if it was hidden before. * * @since 0.15 **/ @@ -1309,9 +1318,9 @@ void msgwin_switch_tab(gint tabnum, gboolean show) /** - * Removes all messages from a tab specified by @a tabnum in the messages window. + * Removes all messages from a tab specified by @a tabnum in the messages window. * - * @param tabnum An index of a tab in the messages window which should be cleared. + * @param tabnum An index of a tab in the messages window which should be cleared. * Valid values are @c MSG_STATUS, @c MSG_COMPILER and @c MSG_MESSAGE. * * @since 0.15 From 78644a8260ae6ee1e8828ad4330275d4685c7a1c Mon Sep 17 00:00:00 2001 From: Thomas Martitz Date: Fri, 26 Jan 2018 07:46:24 +0100 Subject: [PATCH 3/4] msgwin: improve doxygen comments Make the brief text be distinct between msgwin_*_add and msgwin_*_add_string(). Also add @see directives where appropriate. Lastly, add @since to msgwin_status_add() for completeness. --- src/msgwindow.c | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/src/msgwindow.c b/src/msgwindow.c index 79bae392..88e4e817 100644 --- a/src/msgwindow.c +++ b/src/msgwindow.c @@ -317,13 +317,15 @@ static const GdkColor *get_color(gint msg_color) /** - * Adds a new message in the compiler tab treeview in the messages window. + * Adds a formatted message in the compiler tab treeview in the messages window. * * @param msg_color A color to be used for the text. It must be an element of #MsgColors. * @param format @c printf()-style format string. * @param ... Arguments for the @c format string. * - * @since 0.15 + * @see msgwin_compiler_add_string() + * + * @since 0.16 **/ GEANY_API_SYMBOL void msgwin_compiler_add(gint msg_color, const gchar *format, ...) @@ -344,6 +346,8 @@ void msgwin_compiler_add(gint msg_color, const gchar *format, ...) * @param msg_color A color to be used for the text. It must be an element of #MsgColors. * @param msg Compiler message to be added. * + * @see msgwin_compiler_add() + * * @since @todo **/ GEANY_API_SYMBOL @@ -395,7 +399,7 @@ void msgwin_show_hide(gboolean show) /** - * Adds a new message in the messages tab treeview in the messages window. + * Adds a formatted message in the messages tab treeview in the messages window. * * If @a line and @a doc are set, clicking on this line jumps into the file * which is specified by @a doc into the line specified with @a line. @@ -406,7 +410,9 @@ void msgwin_show_hide(gboolean show) * @param format @c printf()-style format string. * @param ... Arguments for the @c format string. * - * @since 0.15 + * @see msgwin_msg_add_string() + * + * @since 0.16 **/ GEANY_API_SYMBOL void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar *format, ...) @@ -434,6 +440,8 @@ void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar * * @param doc @nullable The document. Set to @c NULL to ignore. * @param string Message to be added. * + * @see msgwin_msg_add() + * * @since @todo **/ GEANY_API_SYMBOL @@ -474,12 +482,14 @@ void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const /** - * Logs a status message *without* setting the status bar. + * Logs a new status message *without* setting the status bar. * * Use @ref ui_set_statusbar() to display text on the statusbar. * * @param string Status message to be logged. * + * @see msgwin_status_add() + * * @since @todo **/ GEANY_API_SYMBOL @@ -510,12 +520,16 @@ void msgwin_status_add_string(const gchar *string) } /** - * Logs a status message *without* setting the status bar. + * Logs a formatted status message *without* setting the status bar. * * Use @ref ui_set_statusbar() to display text on the statusbar. * * @param format @c printf()-style format string. * @param ... Arguments for the @c format string. + * + * @see msgwin_status_add_string() + * + * @since 0.12 **/ GEANY_API_SYMBOL void msgwin_status_add(const gchar *format, ...) From bec3832359cf3a7d9f9d5d0a9ac3a622d6387d66 Mon Sep 17 00:00:00 2001 From: Colomban Wendling Date: Thu, 5 Apr 2018 15:35:05 -0400 Subject: [PATCH 4/4] Bump API version --- src/msgwindow.c | 6 +++--- src/plugindata.h | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/msgwindow.c b/src/msgwindow.c index 88e4e817..576a6c98 100644 --- a/src/msgwindow.c +++ b/src/msgwindow.c @@ -348,7 +348,7 @@ void msgwin_compiler_add(gint msg_color, const gchar *format, ...) * * @see msgwin_compiler_add() * - * @since @todo + * @since 1.34 (API 236) **/ GEANY_API_SYMBOL void msgwin_compiler_add_string(gint msg_color, const gchar *msg) @@ -442,7 +442,7 @@ void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar * * * @see msgwin_msg_add() * - * @since @todo + * @since 1.34 (API 236) **/ GEANY_API_SYMBOL void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const gchar *string) @@ -490,7 +490,7 @@ void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const * * @see msgwin_status_add() * - * @since @todo + * @since 1.34 (API 236) **/ GEANY_API_SYMBOL void msgwin_status_add_string(const gchar *string) diff --git a/src/plugindata.h b/src/plugindata.h index f8ddb8e5..d801c2de 100644 --- a/src/plugindata.h +++ b/src/plugindata.h @@ -59,7 +59,7 @@ G_BEGIN_DECLS * @warning You should not test for values below 200 as previously * @c GEANY_API_VERSION was defined as an enum value, not a macro. */ -#define GEANY_API_VERSION 235 +#define GEANY_API_VERSION 236 /* hack to have a different ABI when built with GTK3 because loading GTK2-linked plugins * with GTK3-linked Geany leads to crash */