/* * * GeanyGenDoc, a Geany plugin to ease generation of source code documentation * Copyright (C) 2010-2011 Colomban Wendling * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . * */ #ifdef HAVE_CONFIG_H # include "config.h" /* for the gettext domain */ #endif #include "ggd-plugin.h" #include #include #include /* for the key bindings */ #include #include #include "ggd.h" #include "ggd-file-type.h" #include "ggd-file-type-manager.h" #include "ggd-tag-utils.h" #include "ggd-options.h" /* * Questions: * * how to update tag list? (tm_source_file_buffer_update() is not found in * symbols table) */ /* These items are set by Geany before plugin_init() is called. */ GeanyPlugin *geany_plugin; GeanyData *geany_data; /* TODO check minimum requierment */ PLUGIN_VERSION_CHECK (227) PLUGIN_SET_TRANSLATABLE_INFO ( LOCALEDIR, GETTEXT_PACKAGE, _("Documentation Generator"), _("Generates documentation basis from source code"), GGD_PLUGIN_VERSION, "Colomban Wendling " ) enum { KB_INSERT, NUM_KB }; typedef struct _PluginData { GgdOptGroup *config; GeanyKeyGroup *kb_group; gint editor_menu_popup_line; GtkWidget *separator_item; GtkWidget *edit_menu_item; GtkWidget *tools_menu_item; gulong edit_menu_item_hid; } PluginData; #define plugin (&plugin_data) static PluginData plugin_data = { NULL, NULL, 0, NULL, NULL, NULL, 0l }; /* global plugin options * default values that needs to be set dynamically goes at the top of * load_configuration() */ gchar *GGD_OPT_doctype[GEANY_MAX_BUILT_IN_FILETYPES] = { NULL }; gboolean GGD_OPT_save_to_refresh = FALSE; gboolean GGD_OPT_indent = TRUE; gchar *GGD_OPT_environ = NULL; /* Gets an element of GGD_OPT_doctype, falling back to GGD_OPT_doctype[0] * (default) if the requested element is not set */ static const gchar * ggd_plugin_get_doctype (GeanyFiletypeID id) { const gchar *doctype; g_return_val_if_fail (id >= 0 && id < GEANY_MAX_BUILT_IN_FILETYPES, NULL); doctype = GGD_OPT_doctype[id]; if (! doctype || ! *doctype) { doctype = GGD_OPT_doctype[0]; } return doctype; } /* FIXME: tm_source_file_buffer_update() is not found in symbols table */ /* (tries to) refresh the tag list to the file's current state */ static void refresh_tag_list (TMSourceFile *tm_wo, ScintillaObject *sci, GeanyDocument *doc) { /* gint len; guchar *buf; len = sci_get_length (sci); buf = g_malloc (len + 1); sci_get_text (sci, len + 1, (gchar *)buf); tm_source_file_buffer_update (tm_wo, buf, len, TRUE); g_free (buf); //*/ if (GGD_OPT_save_to_refresh) { document_save_file (doc, FALSE); } } /* tries to insert a comment in the current document * @line: The line for which insert comment, or -1 for the current line */ static void insert_comment (gint line) { GeanyDocument *doc; doc = document_get_current (); if (DOC_VALID (doc)) { /* try to ensure tags corresponds to the actual state of the file */ refresh_tag_list (doc->tm_file, doc->editor->sci, doc); if (line < 0) { line = sci_get_current_line (doc->editor->sci); } ggd_insert_comment (doc, line, ggd_plugin_get_doctype (doc->file_type->id)); } } /* tries to insert comments for all the document */ static void insert_all_comments (void) { GeanyDocument *doc; doc = document_get_current (); if (DOC_VALID (doc)) { /* try to ensure tags corresponds to the actual state of the file */ refresh_tag_list (doc->tm_file, doc->editor->sci, doc); ggd_insert_all_comments (doc, ggd_plugin_get_doctype (doc->file_type->id)); } } /* Escapes a string to use it safely as a GKeyFile key. * It currently replaces only "=" and "#" since GKeyFile supports UTF-8 keys. */ static gchar * normalize_key (const gchar *key) { GString *nkey; nkey = g_string_new (NULL); for (; *key; key++) { switch (*key) { case '=': g_string_append (nkey, "Equal"); break; case '#': g_string_append (nkey, "Sharp"); break; default: g_string_append_c (nkey, *key); break; } } return g_string_free (nkey, FALSE); } static gboolean load_configuration (void) { gboolean success = FALSE; gchar *conffile; GError *err = NULL; guint i; /* default options that needs to be set dynamically */ GGD_OPT_doctype[0] = g_strdup ("doxygen"); plugin->config = ggd_opt_group_new ("General"); ggd_opt_group_add_string (plugin->config, &GGD_OPT_doctype[0], "doctype"); for (i = 1; i < GEANY_MAX_BUILT_IN_FILETYPES; i++) { gchar *name; gchar *normal_ftname; normal_ftname = normalize_key (filetypes[i]->name); name = g_strconcat ("doctype_", normal_ftname, NULL); ggd_opt_group_add_string (plugin->config, &GGD_OPT_doctype[i], name); g_free (name); g_free (normal_ftname); } ggd_opt_group_add_boolean (plugin->config, &GGD_OPT_save_to_refresh, "save_to_refresh"); ggd_opt_group_add_boolean (plugin->config, &GGD_OPT_indent, "indent"); ggd_opt_group_add_string (plugin->config, &GGD_OPT_environ, "environ"); conffile = ggd_get_config_file ("ggd.conf", NULL, GGD_PERM_R, &err); if (conffile) { success = ggd_opt_group_load_from_file (plugin->config, conffile, &err); } if (err) { GLogLevelFlags level = G_LOG_LEVEL_WARNING; if (err->domain == G_FILE_ERROR && err->code == G_FILE_ERROR_NOENT) { level = G_LOG_LEVEL_INFO; } g_log (G_LOG_DOMAIN, level, _("Failed to load configuration: %s"), err->message); g_error_free (err); } g_free (conffile); /* init filetype manager */ ggd_file_type_manager_init (); return success; } static void unload_configuration (void) { gchar *conffile; GError *err = NULL; conffile = ggd_get_config_file ("ggd.conf", NULL, GGD_PERM_RW, &err); if (conffile) { ggd_opt_group_write_to_file (plugin->config, conffile, &err); } if (err) { g_warning (_("Failed to save configuration: %s"), err->message); g_error_free (err); } g_free (conffile); ggd_opt_group_free (plugin->config, TRUE); plugin->config = NULL; /* uninit filetype manager */ ggd_file_type_manager_uninit (); } /* forces reloading of configuration files */ static gboolean reload_configuration (void) { unload_configuration (); return load_configuration (); } /* --- Actual Geany interaction --- */ /* handler for the editor's popup menu entry the plugin adds */ static void editor_menu_acivated_handler (GtkMenuItem *menu_item, PluginData *pdata) { (void)menu_item; insert_comment (pdata->editor_menu_popup_line); } /* hanlder for the keybinding that inserts a comment */ static void insert_comment_keybinding_handler (guint key_id) { (void)key_id; insert_comment (-1); } /* handler for the GeanyDocument::update-editor-menu signal. * It is used to get the line at which menu popuped */ static void update_editor_menu_handler (GObject *obj, const gchar *word, gint pos, GeanyDocument *doc, PluginData *pdata) { pdata->editor_menu_popup_line = sci_get_line_from_position (doc->editor->sci, pos); } /* handler that opens the current filetype's configuration file */ static void open_current_filetype_conf_handler (GtkWidget *widget, gpointer data) { GeanyDocument *doc; (void)widget; (void)data; doc = document_get_current (); if (DOC_VALID (doc)) { gchar *path_read; gchar *path_write; GError *err = NULL; path_write = ggd_file_type_manager_get_conf_path (doc->file_type->id, GGD_PERM_W | GGD_PERM_NOCREAT, &err); if (! path_write) { msgwin_status_add (_("Failed to find configuration file " "for file type \"%s\": %s"), doc->file_type->name, err->message); g_error_free (err); } else { gchar *text = NULL; gchar *path_write_u8; path_read = ggd_file_type_manager_get_conf_path (doc->file_type->id, GGD_PERM_R, &err); if (! path_read) { text = g_strdup (_( "# Configuration for this file type doesn't exist yet.\n" "# To create it, just write it in this file and save it. For the description\n" "# of the syntax of this file, please refer to the manual.\n" )); } else { gchar *content = NULL; gsize length; if (! g_file_get_contents (path_read, &content, &length, &err)) { gchar *display_path_read; display_path_read = g_filename_display_name (path_read); g_warning (_("Failed to load file \"%s\": %s"), display_path_read, err->message); g_free (display_path_read); g_error_free (err); } else { text = encodings_convert_to_utf8 (content, length, NULL); g_free (content); } g_free (path_read); } path_write_u8 = utils_get_utf8_from_locale (path_write); /* It's no Ruby, but it is the closest one I've found. It has: * - # comments * - multi-line double-quoted strings */ document_new_file (path_write_u8, filetypes[GEANY_FILETYPES_RUBY], text); g_free (path_write_u8); g_free (text); g_free (path_write); } } } static void open_manual_handler (GtkWidget *widget, gpointer data) { #ifdef G_OS_WIN32 gchar *prefix = g_win32_get_package_installation_directory_of_module (NULL); #else gchar *prefix = NULL; #endif gchar *path = g_build_filename (prefix ? prefix : "", PLUGINDOCDIR, "/html/manual.html", NULL); utils_open_browser (path); g_free (path); g_free (prefix); } /* handler that reloads the configuration */ static void reload_configuration_hanlder (GtkWidget *widget, gpointer data) { (void)widget; (void)data; reload_configuration (); } /* handler that documents current symbol */ static void document_current_symbol_handler (GObject *obj, gpointer data) { insert_comment (-1); } /* handler that documents all symbols */ static void document_all_symbols_handler (GObject *obj, gpointer data) { insert_all_comments (); } /* FIXME: make menu item appear in the edit menu too */ /* adds the menu item in the editor's popup menu */ static void add_edit_menu_item (PluginData *pdata) { GtkWidget *parent_menu; parent_menu = gtk_menu_item_get_submenu (GTK_MENU_ITEM ( ui_lookup_widget (geany->main_widgets->editor_menu, "comments"))); if (! parent_menu) { parent_menu = geany->main_widgets->editor_menu; pdata->separator_item = gtk_separator_menu_item_new (); gtk_menu_shell_append (GTK_MENU_SHELL (parent_menu), pdata->separator_item); gtk_widget_show (pdata->separator_item); } pdata->edit_menu_item = gtk_menu_item_new_with_label (_("Insert Documentation Comment")); pdata->edit_menu_item_hid = g_signal_connect (pdata->edit_menu_item, "activate", G_CALLBACK (editor_menu_acivated_handler), pdata); gtk_menu_shell_append (GTK_MENU_SHELL (parent_menu), pdata->edit_menu_item); gtk_widget_show (pdata->edit_menu_item); /* make item document-presence sensitive */ ui_add_document_sensitive (pdata->edit_menu_item); /* and attach a keybinding */ keybindings_set_item (pdata->kb_group, KB_INSERT, insert_comment_keybinding_handler, GDK_d, GDK_CONTROL_MASK | GDK_SHIFT_MASK, "instert_doc", _("Insert Documentation Comment"), pdata->edit_menu_item); } /* removes the menu item in the editor's popup menu */ static void remove_edit_menu_item (PluginData *pdata) { g_signal_handler_disconnect (pdata->edit_menu_item, pdata->edit_menu_item_hid); pdata->edit_menu_item_hid = 0l; if (pdata->separator_item) { gtk_widget_destroy (pdata->separator_item); } gtk_widget_destroy (pdata->edit_menu_item); } static GtkWidget * menu_add_item (GtkMenuShell *menu, const gchar *mnemonic, const gchar *tooltip, const gchar *stock_image, GCallback activate_handler, gpointer activate_data) { GtkWidget *item; if (! stock_image) { item = gtk_menu_item_new_with_mnemonic (mnemonic); } else { item = gtk_image_menu_item_new_with_mnemonic (mnemonic); gtk_image_menu_item_set_image (GTK_IMAGE_MENU_ITEM (item), gtk_image_new_from_stock (stock_image, GTK_ICON_SIZE_MENU)); } gtk_widget_set_tooltip_text (item, tooltip); gtk_menu_shell_append (GTK_MENU_SHELL (menu), item); if (activate_handler) { g_signal_connect (item, "activate", activate_handler, activate_data); } return item; } /* creates plugin's tool's menu */ static GtkWidget * create_tools_menu_item (void) { GtkWidget *menu; GtkWidget *item; /* build submenu */ menu = gtk_menu_new (); /* build "document current symbol" item */ item = menu_add_item (GTK_MENU_SHELL (menu), _("_Document Current Symbol"), _("Generate documentation for the current symbol"), NULL, G_CALLBACK (document_current_symbol_handler), NULL); ui_add_document_sensitive (item); /* build "document all" item */ item = menu_add_item (GTK_MENU_SHELL (menu), _("Document _All Symbols"), _("Generate documentation for all symbols in the " "current document"), NULL, G_CALLBACK (document_all_symbols_handler), NULL); ui_add_document_sensitive (item); /* separator */ item = gtk_separator_menu_item_new (); gtk_menu_shell_append (GTK_MENU_SHELL (menu), item); /* build "reload" item */ item = menu_add_item (GTK_MENU_SHELL (menu), _("_Reload Configuration Files"), _("Force reloading of the configuration files"), GTK_STOCK_REFRESH, G_CALLBACK (reload_configuration_hanlder), NULL); /* language filetypes opener */ item = menu_add_item (GTK_MENU_SHELL (menu), _("_Edit Current Language Configuration"), _("Open the current language configuration file for " "editing"), GTK_STOCK_EDIT, G_CALLBACK (open_current_filetype_conf_handler), NULL); ui_add_document_sensitive (item); /* separator */ item = gtk_separator_menu_item_new (); gtk_menu_shell_append (GTK_MENU_SHELL (menu), item); /* help/manual opening */ item = menu_add_item (GTK_MENU_SHELL (menu), _("Open _Manual"), _("Open the manual in a browser"), GTK_STOCK_HELP, G_CALLBACK (open_manual_handler), NULL); /* build tools menu item */ item = gtk_menu_item_new_with_mnemonic (_("_Documentation Generator")); gtk_menu_item_set_submenu (GTK_MENU_ITEM (item), menu); gtk_widget_show_all (item); return item; } /* build plugin's menus */ static void build_menus (PluginData *pdata) { add_edit_menu_item (pdata); pdata->tools_menu_item = create_tools_menu_item (); gtk_menu_shell_append (GTK_MENU_SHELL (geany->main_widgets->tools_menu), pdata->tools_menu_item); } /* destroys plugin's menus */ static void destroy_menus (PluginData *pdata) { gtk_widget_destroy (pdata->tools_menu_item); pdata->tools_menu_item = NULL; remove_edit_menu_item (pdata); } void plugin_init (GeanyData *data G_GNUC_UNUSED) { plugin->kb_group = plugin_set_key_group (geany_plugin, GGD_PLUGIN_CNAME, NUM_KB, NULL); load_configuration (); build_menus (plugin); plugin_signal_connect (geany_plugin, NULL, "update-editor-menu", FALSE, G_CALLBACK (update_editor_menu_handler), plugin); } void plugin_cleanup (void) { destroy_menus (plugin); unload_configuration (); plugin->kb_group = NULL; } void plugin_help (void) { open_manual_handler (NULL, NULL); } /* --- Configuration dialog --- */ #include "ggd-widget-frame.h" #include "ggd-widget-doctype-selector.h" static GtkWidget *GGD_W_doctype_selector; static void conf_dialog_response_handler (GtkDialog *dialog, gint response_id, PluginData *pdata) { switch (response_id) { case GTK_RESPONSE_ACCEPT: case GTK_RESPONSE_APPLY: case GTK_RESPONSE_OK: case GTK_RESPONSE_YES: { guint i; ggd_opt_group_sync_from_proxies (pdata->config); for (i = 0; i < GEANY_MAX_BUILT_IN_FILETYPES; i++) { g_free (GGD_OPT_doctype[i]); GGD_OPT_doctype[i] = ggd_doctype_selector_get_doctype (GGD_DOCTYPE_SELECTOR (GGD_W_doctype_selector), i); } break; } default: break; } } GtkWidget * plugin_configure (GtkDialog *dialog) { GtkWidget *box; GtkWidget *box2; GtkWidget *frame; GtkWidget *widget; guint i; g_signal_connect (dialog, "response", G_CALLBACK (conf_dialog_response_handler), plugin); box = gtk_vbox_new (FALSE, 12); /* General */ frame = ggd_frame_new (_("General")); gtk_box_pack_start (GTK_BOX (box), frame, FALSE, FALSE, 0); box2 = gtk_vbox_new (FALSE, 0); gtk_container_add (GTK_CONTAINER (frame), box2); /* auto-save */ widget = gtk_check_button_new_with_mnemonic (_("_Save file before generating " "documentation")); gtk_widget_set_tooltip_text (widget, _("Whether the current document should be saved to disc before generating " "the documentation. This is a technical detail, but it is currently " "needed to have an up-to-date tag list. If you disable this option and " "ask for documentation generation on a modified document, the behavior " "may be surprising since the comment will be generated for the last " "saved state of this document and not the current one.")); ggd_opt_group_set_proxy_gtktogglebutton (plugin->config, &GGD_OPT_save_to_refresh, widget); gtk_box_pack_start (GTK_BOX (box2), widget, FALSE, FALSE, 0); /* indent */ widget = gtk_check_button_new_with_mnemonic (_("_Indent inserted documentation")); gtk_widget_set_tooltip_text (widget, _("Whether the inserted documentation should be indented to fit the " "indentation at the insertion position.")); ggd_opt_group_set_proxy_gtktogglebutton (plugin->config, &GGD_OPT_indent, widget); gtk_box_pack_start (GTK_BOX (box2), widget, FALSE, FALSE, 0); /* Documentation type */ frame = ggd_frame_new (_("Documentation type")); gtk_box_pack_start (GTK_BOX (box), frame, TRUE, TRUE, 0); box2 = gtk_vbox_new (FALSE, 0); gtk_container_add (GTK_CONTAINER (frame), box2); GGD_W_doctype_selector = ggd_doctype_selector_new (); for (i = 0; i < GEANY_MAX_BUILT_IN_FILETYPES; i++) { ggd_doctype_selector_set_doctype (GGD_DOCTYPE_SELECTOR (GGD_W_doctype_selector), i, GGD_OPT_doctype[i]); } gtk_widget_set_tooltip_text (GGD_W_doctype_selector, _("Choose the documentation type to use with each file type. The special " "language \"All\" on top of the list is used to choose the default " "documentation type, used for all languages that haven't one set.")); gtk_box_pack_start (GTK_BOX (box2), GGD_W_doctype_selector, TRUE, TRUE, 0); /* Environ editor */ widget = ggd_frame_new (_("Global environment")); gtk_widget_set_tooltip_text (widget, _("Global environment overrides and additions. This environment will be " "merged with the file-type-specific ones.")); { GtkWidget *scrolled; GtkWidget *view; GObject *proxy; scrolled = gtk_scrolled_window_new (NULL, NULL); gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC); gtk_scrolled_window_set_shadow_type (GTK_SCROLLED_WINDOW (scrolled), GTK_SHADOW_IN); gtk_container_add (GTK_CONTAINER (widget), scrolled); view = gtk_text_view_new (); proxy = G_OBJECT (gtk_text_view_get_buffer (GTK_TEXT_VIEW (view))); ggd_opt_group_set_proxy (plugin->config, &GGD_OPT_environ, proxy, "text"); gtk_container_add (GTK_CONTAINER (scrolled), view); } gtk_box_pack_start (GTK_BOX (box), widget, TRUE, TRUE, 0); gtk_widget_show_all (box); return box; }