From c8c3f4696f982d27c11a747b0188b4d144825cd9 Mon Sep 17 00:00:00 2001 From: JosephMcc Date: Sat, 11 Feb 2017 18:28:38 -0800 Subject: [PATCH] docs: Start cleaning up the docs The code has chaged quite a bit. Start updating the docs to match and to quiet some warnings during build. --- docs/reference/Makefile.am | 69 +++++----------- .../reference/{xed-docs.sgml => xed-docs.xml} | 18 ++++- docs/reference/xed-sections.txt | 79 ++++++++----------- docs/reference/xed.types | 26 ------ xed/Makefile.am | 2 +- xed/xed-commands-file.c | 13 +-- xed/xed-document.c | 8 +- xed/xed-encodings-combo-box.c | 33 ++++++-- xed/xed-encodings-combo-box.h | 2 +- xed/xed-progress-info-bar.c | 6 +- xed/xed-progress-info-bar.h | 4 +- xed/xed-statusbar.h | 2 - 12 files changed, 112 insertions(+), 150 deletions(-) rename docs/reference/{xed-docs.sgml => xed-docs.xml} (72%) delete mode 100644 docs/reference/xed.types diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 805e124..8f9e1e9 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -6,41 +6,30 @@ AUTOMAKE_OPTIONS = 1.6 # The name of the module, e.g. 'glib'. -DOC_MODULE=xed +DOC_MODULE = xed -# The top-level SGML file. You can change this if you want to. -DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml +# The top-level XML file (SGML in the past). +DOC_MAIN_SGML_FILE = xed-docs.xml # The directory containing the source code. Relative to $(srcdir). -# gtk-doc will search all .c & .h files beneath here for inline comments -# documenting the functions and macros. -DOC_SOURCE_DIR=../../xed - -# Extra options to pass to gtkdoc-scangobj. Not normally needed. -SCANGOBJ_OPTIONS= +DOC_SOURCE_DIR = ../../xed # Extra options to supply to gtkdoc-scan. -# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +# e.g. SCAN_OPTIONS = --deprecated-guards="GTK_DISABLE_DEPRECATED" SCAN_OPTIONS = --rebuild-types # Extra options to supply to gtkdoc-mkdb. -MKDB_OPTIONS=--sgml-mode --output-format=xml - -# Extra options to supply to gtkdoc-mktmpl -# e.g. MKTMPL_OPTIONS=--only-section-tmpl -MKTMPL_OPTIONS= - -# Extra options to supply to gtkdoc-fixref. Not normally needed. -# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html -FIXXREF_OPTIONS= +MKDB_OPTIONS = --xml-mode --output-format=xml # Used for dependencies. The docs will be rebuilt if any of these change. -HFILE_GLOB=$(top_srcdir)/xed/*.h -CFILE_GLOB=$(top_srcdir)/xed/*.c +HFILE_GLOB = $(top_srcdir)/xed/*.h +CFILE_GLOB = $(top_srcdir)/xed/*.c # Header files to ignore when scanning (These are internal to xed). IGNORE_HFILES= \ - xed-commands.h \ + xed-close-confirmation-dialog.h \ + xed-dirs.h \ + xed-commands.h \ xed-documents-panel.h \ xed-io-error-info-bar.h \ xed-languages-manager.h \ @@ -49,7 +38,6 @@ IGNORE_HFILES= \ xed-ui.h \ xed-window-private.h \ xed-output-window.h \ - xed-close-confirmation-dialog.h \ xed-encodings-dialog.h \ xed-open-location-dialog.h \ xed-page-setup-dialog.h \ @@ -58,35 +46,23 @@ IGNORE_HFILES= \ xed-marshal.h \ xed-enum-types.h -# These files are not part of xed but were copied into it for some reason. -# Do not parse them to make the docs. -IGNORE_HFILES += \ - bacon-message-connection.h \ - sexy-icon-entry.h - # Images to copy into HTML directory. -HTML_IMAGES= +HTML_IMAGES = # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). -# e.g. content_files=running.sgml building.sgml changes-2.0.sgml -content_files= - -# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded -# These files must be listed here *and* in content_files -# e.g. expand_content_files=running.sgml -expand_content_files= +content_files = # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. # Only needed if you are using gtkdoc-scangobj to dynamically query widget # signals and properties. -GTKDOC_CFLAGS= \ - -I$(top_srcdir)/xed \ - -I$(top_builddir)/xed \ - -I$(top_srcdir) \ - -I$(top_builddir) \ +GTKDOC_CFLAGS = \ + -I$(top_srcdir)/xed \ + -I$(top_builddir)/xed \ + -I$(top_srcdir) \ + -I$(top_builddir) \ $(XED_CFLAGS) -GTKDOC_LIBS= \ +GTKDOC_LIBS = \ $(top_builddir)/xed/libxed.la \ $(XED_LIBS) @@ -95,11 +71,4 @@ MAINTAINERCLEANFILES = xed.types # This includes the standard gtk-doc make rules, copied by gtkdocize. include $(top_srcdir)/gtk-doc.make -# Other files to distribute -# e.g. EXTRA_DIST += version.xml.in - -regenerate-types: - grep _get_type $(DOC_SOURCE_DIR)/xed-*.h | grep -oR '^.*\.h' | sort | uniq - | sed -r 's/^.*\.h$/#include "\0"/' > xed.types - grep _get_type $(DOC_SOURCE_DIR)/xed-*.h | grep -oR '^.*\.h' | sort | uniq - | sed -re 'y/-/_/' -e 's/^(.*)\.h$/\1_get_type/' >> xed.types.new - -include $(top_srcdir)/git.mk diff --git a/docs/reference/xed-docs.sgml b/docs/reference/xed-docs.xml similarity index 72% rename from docs/reference/xed-docs.sgml rename to docs/reference/xed-docs.xml index b269b2b..54932cd 100644 --- a/docs/reference/xed-docs.sgml +++ b/docs/reference/xed-docs.xml @@ -11,7 +11,7 @@ - + @@ -20,7 +20,7 @@ - + @@ -29,7 +29,19 @@ - + + + Object Hierarchy + + + + + Index of all symbols + + + + + diff --git a/docs/reference/xed-sections.txt b/docs/reference/xed-sections.txt index 53de7b5..9987051 100644 --- a/docs/reference/xed-sections.txt +++ b/docs/reference/xed-sections.txt @@ -1,14 +1,13 @@
xed-app -XedAppPrivate XedApp XedApp -xed_app_get_default xed_app_create_window -xed_app_get_windows -xed_app_get_active_window +xed_app_set_window_title +xed_app_get_main_windows xed_app_get_documents xed_app_get_views +xed_app_show_help XED_APP XED_IS_APP @@ -41,17 +40,18 @@ XedDocumentPrivate XedDocument xed_document_new xed_document_get_file -xed_document_get_location xed_document_get_uri_for_display xed_document_get_short_name_for_display +xed_document_set_short_name_for_display xed_document_get_mime_type xed_document_get_readonly -xed_document_insert_file xed_document_is_untouched xed_document_is_untitled xed_document_get_deleted xed_document_goto_line +xed_document_goto_line_offset xed_document_set_language +xed_document_get_metadata XED_DOCUMENT XED_IS_DOCUMENT @@ -63,21 +63,20 @@ XED_DOCUMENT_GET_CLASS
-xed-encodings-option-menu -XedEncodingsOptionMenuPrivate +xed-encodings-combo-box XedEncodingsOptionMenu -XedEncodingsOptionMenu -xed_encodings_option_menu_new -xed_encodings_option_menu_get_selected_encoding -xed_encodings_option_menu_set_selected_encoding +XedEncodingsComboBox +xed_encodings_combo_box_new +xed_encodings_combo_box_get_selected_encoding +xed_encodings_combo_box_set_selected_encoding -XED_ENCODINGS_OPTION_MENU -XED_IS_ENCODINGS_OPTION_MENU -XED_TYPE_ENCODINGS_OPTION_MENU -xed_encodings_option_menu_get_type -XED_ENCODINGS_OPTION_MENU_CLASS -XED_IS_ENCODINGS_OPTION_MENU_CLASS -XED_ENCODINGS_OPTION_MENU_GET_CLASS +XED_ENCODINGS_COMBO_BOX +XED_IS_ENCODINGS_COMBO_BOX +XED_TYPE_ENCODINGS_COMBO_BOX +xed_encodings_combo_box_get_type +XED_ENCODINGS_COMBO_BOX_CLASS +XED_IS_ENCODINGS_COMBO_BOX_CLASS +XED_ENCODINGS_COMBO_BOX_GET_CLASS
@@ -264,33 +263,30 @@ XED_PRINT_JOB_GET_CLASS
-xed-progress-message-area -XedProgressMessageAreaPrivate -XedProgressMessageArea -XedProgressMessageArea -xed_progress_message_area_new -xed_progress_message_area_set_image -xed_progress_message_area_set_markup -xed_progress_message_area_set_text -xed_progress_message_area_set_fraction -xed_progress_message_area_pulse +xed-progress-info-bar +XedProgressInfoBar +XedProgressInfoBar +xed_progress_info_bar_new +xed_progress_info_bar_set_icon_name +xed_progress_info_bar_set_markup +xed_progress_info_bar_set_text +xed_progress_info_bar_set_fraction +xed_progress_info_bar_pulse -XED_PROGRESS_MESSAGE_AREA -XED_IS_PROGRESS_MESSAGE_AREA -XED_TYPE_PROGRESS_MESSAGE_AREA -xed_progress_message_area_get_type -XED_PROGRESS_MESSAGE_AREA_CLASS -XED_IS_PROGRESS_MESSAGE_AREA_CLASS -XED_PROGRESS_MESSAGE_AREA_GET_CLASS +XED_PROGRESS_INFO_BAR +XED_IS_PROGRESS_INFO_BAR +XED_TYPE_PROGRESS_INFO_BAR +xed_progress_info_bar_get_type +XED_PROGRESS_INFO_BAR_CLASS +XED_IS_PROGRESS_INFO_BAR_CLASS +XED_PROGRESS_INFO_BAR_GET_CLASS
xed-statusbar -XedStatusbarPrivate XedStatusbar XedStatusbar xed_statusbar_new -XedStatus xed_statusbar_set_window_state xed_statusbar_set_overwrite xed_statusbar_set_cursor_position @@ -457,13 +453,6 @@ xed_debug_message xed_help_display
-
-xed-metadata-manager -xed_metadata_manager_shutdown -xed_metadata_manager_get -xed_metadata_manager_set -
-
xed-utils GBOOLEAN_TO_POINTER diff --git a/docs/reference/xed.types b/docs/reference/xed.types deleted file mode 100644 index 8c34ddd..0000000 --- a/docs/reference/xed.types +++ /dev/null @@ -1,26 +0,0 @@ -xed_app_activatable_get_type -xed_app_get_type -xed_close_button_get_type -xed_document_get_type -xed_encodings_combo_box_get_type -xed_file_chooser_dialog_get_type -xed_history_entry_get_type -xed_message_bus_get_type -xed_message_get_type -xed_message_type_get_type -xed_notebook_get_type -xed_panel_get_type -xed_print_job_get_type -xed_print_preview_get_type -xed_progress_message_area_get_type -xed_searchbar_get_type -xed_settings_get_type -xed_status_combo_box_get_type -xed_statusbar_get_type -xed_tab_get_type -xed_tab_label_get_type -xed_view_activatable_get_type -xed_view_frame_get_type -xed_view_get_type -xed_window_activatable_get_type -xed_window_get_type diff --git a/xed/Makefile.am b/xed/Makefile.am index 284e028..d5610d7 100644 --- a/xed/Makefile.am +++ b/xed/Makefile.am @@ -80,7 +80,7 @@ INST_H_FILES = \ xed-window-activatable.h if !ENABLE_GVFS_METADATA -INST_H_FILES += xed-metadata-manager.h +NOINST_H_FILES += xed-metadata-manager.h endif headerdir = $(prefix)/include/xed diff --git a/xed/xed-commands-file.c b/xed/xed-commands-file.c index 7602efe..bf5bc9e 100644 --- a/xed/xed-commands-file.c +++ b/xed/xed-commands-file.c @@ -289,14 +289,15 @@ xed_commands_load_location (XedWindow *window, /** * xed_commands_load_locations: - * @window: - * @locations: (element-type GLib.File) (transfer none): - * @encoding: (allow-none): - * @line_pos: + * @window: a #XedWindow + * @locations: (element-type Gio.File): the locations to load + * @encoding: (allow-none): the #GtkSourceEncoding + * @line_pos: the line position to place the cursor * - * Ignore non-existing locations + * Loads @locataions. Ignore non-existing locations * - * Returns: + * Returns: (element-type Xed.Document) (transfer container): the locations + * that were loaded. */ GSList * xed_commands_load_locations (XedWindow *window, diff --git a/xed/xed-document.c b/xed/xed-document.c index 30a5fa9..44f27f3 100644 --- a/xed/xed-document.c +++ b/xed/xed-document.c @@ -832,7 +832,7 @@ xed_document_set_location (XedDocument *doc, /** * xed_document_get_uri_for_display: - * @doc: + * @doc: a #XedDocument * * Note: this never returns %NULL. **/ @@ -857,7 +857,7 @@ xed_document_get_uri_for_display (XedDocument *doc) /** * xed_document_get_short_name_for_display: - * @doc: + * @doc: a #XedDocument * * Note: this never returns %NULL. **/ @@ -911,7 +911,7 @@ xed_document_get_content_type (XedDocument *doc) /** * xed_document_get_mime_type: - * @doc: + * @doc: a #XedDocument * * Note: this never returns %NULL. **/ @@ -1461,7 +1461,7 @@ xed_document_set_metadata (XedDocument *doc, * * Gets the metadata assigned to @key. * - * Returns: the value assigned to @key. + * Returns: the value assigned to @key. Free with g_free(). */ gchar * xed_document_get_metadata (XedDocument *doc, diff --git a/xed/xed-encodings-combo-box.c b/xed/xed-encodings-combo-box.c index 257fc21..11d0bb7 100644 --- a/xed/xed-encodings-combo-box.c +++ b/xed/xed-encodings-combo-box.c @@ -33,16 +33,14 @@ #include #endif -#include -#include +#include "xed-encodings-combo-box.h" + +#include -#include "xed/xed-encodings-combo-box.h" #include #include "xed-settings.h" #include "xed-utils.h" -#define ENCODING_KEY "Enconding" - #define XED_ENCODINGS_COMBO_BOX_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE ((object), \ XED_TYPE_ENCODINGS_COMBO_BOX, \ XedEncodingsComboBoxPrivate)) @@ -386,6 +384,17 @@ xed_encodings_combo_box_init (XedEncodingsComboBox *menu) update_menu (menu); } +/** + * xed_encodings_combo_box_new: + * @save_mode: whether the combo box is used for saving a content. + * + * Creates a new encodings combo box object. If @save_mode is %FALSE, it means + * that the combo box is used for loading a content (e.g. a file), so the row + * "Automatically Detected" is added. For saving a content, the encoding must be + * provided. + * + * Returns: a new #XedEncodingsComboBox object. + */ GtkWidget * xed_encodings_combo_box_new (gboolean save_mode) { @@ -394,6 +403,13 @@ xed_encodings_combo_box_new (gboolean save_mode) NULL); } +/** + * xed_encodings_combo_box_get_selected_encoding: + * @menu: a #XedEncodingsComboBox. + * + * Returns: the selected #GtkSourceEncoding, or %NULL if the encoding should be + * auto-detected (only for loading mode, not for saving). + */ const GtkSourceEncoding * xed_encodings_combo_box_get_selected_encoding (XedEncodingsComboBox *menu) { @@ -418,8 +434,10 @@ xed_encodings_combo_box_get_selected_encoding (XedEncodingsComboBox *menu) /** * xed_encodings_combo_box_set_selected_encoding: - * @menu: - * @encoding: (allow-none): + * @menu: a #XedEncodingsComboBox + * @encoding: the #GtkSourceEncoding + * + * Sets the selected encoding. **/ void xed_encodings_combo_box_set_selected_encoding (XedEncodingsComboBox *menu, @@ -428,6 +446,7 @@ xed_encodings_combo_box_set_selected_encoding (XedEncodingsComboBox *menu, GtkTreeIter iter; GtkTreeModel *model; gboolean b; + g_return_if_fail (XED_IS_ENCODINGS_COMBO_BOX (menu)); g_return_if_fail (GTK_IS_COMBO_BOX (menu)); diff --git a/xed/xed-encodings-combo-box.h b/xed/xed-encodings-combo-box.h index 556dc44..9fe5936 100644 --- a/xed/xed-encodings-combo-box.h +++ b/xed/xed-encodings-combo-box.h @@ -32,7 +32,7 @@ #ifndef __XED_ENCODINGS_COMBO_BOX_H__ #define __XED_ENCODINGS_COMBO_BOX_H__ -#include +#include G_BEGIN_DECLS diff --git a/xed/xed-progress-info-bar.c b/xed/xed-progress-info-bar.c index 837be74..fc3f98d 100644 --- a/xed/xed-progress-info-bar.c +++ b/xed/xed-progress-info-bar.c @@ -179,15 +179,15 @@ xed_progress_info_bar_new (const gchar *icon_name, "has-cancel-button", has_cancel, NULL)); - xed_progress_info_bar_set_image (bar, icon_name); + xed_progress_info_bar_set_icon_name (bar, icon_name); xed_progress_info_bar_set_markup (bar, markup); return GTK_WIDGET (bar); } void -xed_progress_info_bar_set_image (XedProgressInfoBar *bar, - const gchar *icon_name) +xed_progress_info_bar_set_icon_name (XedProgressInfoBar *bar, + const gchar *icon_name) { g_return_if_fail (XED_IS_PROGRESS_INFO_BAR (bar)); g_return_if_fail (icon_name != NULL); diff --git a/xed/xed-progress-info-bar.h b/xed/xed-progress-info-bar.h index 0c0da77..822816c 100644 --- a/xed/xed-progress-info-bar.h +++ b/xed/xed-progress-info-bar.h @@ -65,8 +65,8 @@ GtkWidget *xed_progress_info_bar_new (const gchar *icon_name, const gchar *markup, gboolean has_cancel); -void xed_progress_info_bar_set_image (XedProgressInfoBar *area, - const gchar *icon_name); +void xed_progress_info_bar_set_icon_name (XedProgressInfoBar *area, + const gchar *icon_name); void xed_progress_info_bar_set_markup (XedProgressInfoBar *area, const gchar *markup); diff --git a/xed/xed-statusbar.h b/xed/xed-statusbar.h index 47c8002..7f00d2f 100644 --- a/xed/xed-statusbar.h +++ b/xed/xed-statusbar.h @@ -62,8 +62,6 @@ GType xed_statusbar_get_type (void) G_GNUC_CONST; GtkWidget *xed_statusbar_new (void); -/* FIXME: status is not defined in any .h */ -#define XedStatus gint void xed_statusbar_set_window_state (XedStatusbar *statusbar, XedWindowState state, gint num_of_errors);