wp
/
xed
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

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.
This commit is contained in:
JosephMcc 2017-02-11 18:28:38 -08:00
parent 98c983f144
commit c8c3f4696f
12 changed files with 112 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/reference/Makefile.am
View File

@ -8,31 +8,18 @@ AUTOMAKE_OPTIONS = 1.6
# The name of the module, e.g. 'glib'. # 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. # The top-level XML file (SGML in the past).
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml DOC_MAIN_SGML_FILE = xed-docs.xml
# The directory containing the source code. Relative to $(srcdir). # 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 DOC_SOURCE_DIR = ../../xed
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=
# Extra options to supply to gtkdoc-scan. # 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 SCAN_OPTIONS = --rebuild-types
# Extra options to supply to gtkdoc-mkdb. # Extra options to supply to gtkdoc-mkdb.
MKDB_OPTIONS=--sgml-mode --output-format=xml MKDB_OPTIONS = --xml-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=
# Used for dependencies. The docs will be rebuilt if any of these change. # Used for dependencies. The docs will be rebuilt if any of these change.
HFILE_GLOB = $(top_srcdir)/xed/*.h HFILE_GLOB = $(top_srcdir)/xed/*.h
@ -40,6 +27,8 @@ CFILE_GLOB=$(top_srcdir)/xed/*.c
# Header files to ignore when scanning (These are internal to xed). # Header files to ignore when scanning (These are internal to xed).
IGNORE_HFILES= \ IGNORE_HFILES= \
xed-close-confirmation-dialog.h \
xed-dirs.h \
xed-commands.h \ xed-commands.h \
xed-documents-panel.h \ xed-documents-panel.h \
xed-io-error-info-bar.h \ xed-io-error-info-bar.h \
@ -49,7 +38,6 @@ IGNORE_HFILES= \
xed-ui.h \ xed-ui.h \
xed-window-private.h \ xed-window-private.h \
xed-output-window.h \ xed-output-window.h \
xed-close-confirmation-dialog.h \
xed-encodings-dialog.h \ xed-encodings-dialog.h \
xed-open-location-dialog.h \ xed-open-location-dialog.h \
xed-page-setup-dialog.h \ xed-page-setup-dialog.h \
@ -58,24 +46,12 @@ IGNORE_HFILES= \
xed-marshal.h \ xed-marshal.h \
xed-enum-types.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. # Images to copy into HTML directory.
HTML_IMAGES = HTML_IMAGES =
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). # 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 = 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=
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget # Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties. # signals and properties.
@ -95,11 +71,4 @@ MAINTAINERCLEANFILES = xed.types
# This includes the standard gtk-doc make rules, copied by gtkdocize. # This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/gtk-doc.make 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 -include $(top_srcdir)/git.mk

18
docs/reference/xed-docs.sgml → docs/reference/xed-docs.xml
View File

@ -11,7 +11,7 @@
<xi:include href="xml/xed-app.xml"/> <xi:include href="xml/xed-app.xml"/>
<xi:include href="xml/xed-app-activatable.xml"/> <xi:include href="xml/xed-app-activatable.xml"/>
<xi:include href="xml/xed-document.xml"/> <xi:include href="xml/xed-document.xml"/>
<xi:include href="xml/xed-encodings-option-menu.xml"/> <xi:include href="xml/xed-encodings-combo-box.xml"/>
<xi:include href="xml/xed-file-chooser-dialog.xml"/> <xi:include href="xml/xed-file-chooser-dialog.xml"/>
<xi:include href="xml/xed-message-bus.xml"/> <xi:include href="xml/xed-message-bus.xml"/>
<xi:include href="xml/xed-message-type.xml"/> <xi:include href="xml/xed-message-type.xml"/>
@ -20,7 +20,7 @@
<xi:include href="xml/xed-panel.xml"/> <xi:include href="xml/xed-panel.xml"/>
<xi:include href="xml/xed-print-job-preview.xml"/> <xi:include href="xml/xed-print-job-preview.xml"/>
<xi:include href="xml/xed-print-job.xml"/> <xi:include href="xml/xed-print-job.xml"/>
<xi:include href="xml/xed-progress-message-area.xml"/> <xi:include href="xml/xed-progress-info-bar.xml"/>
<xi:include href="xml/xed-statusbar.xml"/> <xi:include href="xml/xed-statusbar.xml"/>
<xi:include href="xml/xed-tab.xml"/> <xi:include href="xml/xed-tab.xml"/>
<xi:include href="xml/xed-view.xml"/> <xi:include href="xml/xed-view.xml"/>
@ -29,7 +29,19 @@
<xi:include href="xml/xed-convert.xml"/> <xi:include href="xml/xed-convert.xml"/>
<xi:include href="xml/xed-debug.xml"/> <xi:include href="xml/xed-debug.xml"/>
<xi:include href="xml/xed-help.xml"/> <xi:include href="xml/xed-help.xml"/>
<xi:include href="xml/xed-metadata-manager.xml"/>
<xi:include href="xml/xed-utils.xml"/> <xi:include href="xml/xed-utils.xml"/>
</chapter> </chapter>
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<index id="api-index-full">
<title>Index of all symbols</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book> </book>

79
docs/reference/xed-sections.txt
View File

@ -1,14 +1,13 @@
<SECTION> <SECTION>
<FILE>xed-app</FILE> <FILE>xed-app</FILE>
XedAppPrivate
<TITLE>XedApp</TITLE> <TITLE>XedApp</TITLE>
XedApp XedApp
xed_app_get_default
xed_app_create_window xed_app_create_window
xed_app_get_windows xed_app_set_window_title
xed_app_get_active_window xed_app_get_main_windows
xed_app_get_documents xed_app_get_documents
xed_app_get_views xed_app_get_views
xed_app_show_help
<SUBSECTION Standard> <SUBSECTION Standard>
XED_APP XED_APP
XED_IS_APP XED_IS_APP
@ -41,17 +40,18 @@ XedDocumentPrivate
XedDocument XedDocument
xed_document_new xed_document_new
xed_document_get_file xed_document_get_file
xed_document_get_location
xed_document_get_uri_for_display xed_document_get_uri_for_display
xed_document_get_short_name_for_display xed_document_get_short_name_for_display
xed_document_set_short_name_for_display
xed_document_get_mime_type xed_document_get_mime_type
xed_document_get_readonly xed_document_get_readonly
xed_document_insert_file
xed_document_is_untouched xed_document_is_untouched
xed_document_is_untitled xed_document_is_untitled
xed_document_get_deleted xed_document_get_deleted
xed_document_goto_line xed_document_goto_line
xed_document_goto_line_offset
xed_document_set_language xed_document_set_language
xed_document_get_metadata
<SUBSECTION Standard> <SUBSECTION Standard>
XED_DOCUMENT XED_DOCUMENT
XED_IS_DOCUMENT XED_IS_DOCUMENT
@ -63,21 +63,20 @@ XED_DOCUMENT_GET_CLASS
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>xed-encodings-option-menu</FILE> <FILE>xed-encodings-combo-box</FILE>
XedEncodingsOptionMenuPrivate
<TITLE>XedEncodingsOptionMenu</TITLE> <TITLE>XedEncodingsOptionMenu</TITLE>
XedEncodingsOptionMenu XedEncodingsComboBox
xed_encodings_option_menu_new xed_encodings_combo_box_new
xed_encodings_option_menu_get_selected_encoding xed_encodings_combo_box_get_selected_encoding
xed_encodings_option_menu_set_selected_encoding xed_encodings_combo_box_set_selected_encoding
<SUBSECTION Standard> <SUBSECTION Standard>
XED_ENCODINGS_OPTION_MENU XED_ENCODINGS_COMBO_BOX
XED_IS_ENCODINGS_OPTION_MENU XED_IS_ENCODINGS_COMBO_BOX
XED_TYPE_ENCODINGS_OPTION_MENU XED_TYPE_ENCODINGS_COMBO_BOX
xed_encodings_option_menu_get_type xed_encodings_combo_box_get_type
XED_ENCODINGS_OPTION_MENU_CLASS XED_ENCODINGS_COMBO_BOX_CLASS
XED_IS_ENCODINGS_OPTION_MENU_CLASS XED_IS_ENCODINGS_COMBO_BOX_CLASS
XED_ENCODINGS_OPTION_MENU_GET_CLASS XED_ENCODINGS_COMBO_BOX_GET_CLASS
</SECTION> </SECTION>
<SECTION> <SECTION>
@ -264,33 +263,30 @@ XED_PRINT_JOB_GET_CLASS
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>xed-progress-message-area</FILE> <FILE>xed-progress-info-bar</FILE>
XedProgressMessageAreaPrivate <TITLE>XedProgressInfoBar</TITLE>
<TITLE>XedProgressMessageArea</TITLE> XedProgressInfoBar
XedProgressMessageArea xed_progress_info_bar_new
xed_progress_message_area_new xed_progress_info_bar_set_icon_name
xed_progress_message_area_set_image xed_progress_info_bar_set_markup
xed_progress_message_area_set_markup xed_progress_info_bar_set_text
xed_progress_message_area_set_text xed_progress_info_bar_set_fraction
xed_progress_message_area_set_fraction xed_progress_info_bar_pulse
xed_progress_message_area_pulse
<SUBSECTION Standard> <SUBSECTION Standard>
XED_PROGRESS_MESSAGE_AREA XED_PROGRESS_INFO_BAR
XED_IS_PROGRESS_MESSAGE_AREA XED_IS_PROGRESS_INFO_BAR
XED_TYPE_PROGRESS_MESSAGE_AREA XED_TYPE_PROGRESS_INFO_BAR
xed_progress_message_area_get_type xed_progress_info_bar_get_type
XED_PROGRESS_MESSAGE_AREA_CLASS XED_PROGRESS_INFO_BAR_CLASS
XED_IS_PROGRESS_MESSAGE_AREA_CLASS XED_IS_PROGRESS_INFO_BAR_CLASS
XED_PROGRESS_MESSAGE_AREA_GET_CLASS XED_PROGRESS_INFO_BAR_GET_CLASS
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>xed-statusbar</FILE> <FILE>xed-statusbar</FILE>
XedStatusbarPrivate
<TITLE>XedStatusbar</TITLE> <TITLE>XedStatusbar</TITLE>
XedStatusbar XedStatusbar
xed_statusbar_new xed_statusbar_new
XedStatus
xed_statusbar_set_window_state xed_statusbar_set_window_state
xed_statusbar_set_overwrite xed_statusbar_set_overwrite
xed_statusbar_set_cursor_position xed_statusbar_set_cursor_position
@ -457,13 +453,6 @@ xed_debug_message
xed_help_display xed_help_display
</SECTION> </SECTION>
<SECTION>
<FILE>xed-metadata-manager</FILE>
xed_metadata_manager_shutdown
xed_metadata_manager_get
xed_metadata_manager_set
</SECTION>
<SECTION> <SECTION>
<FILE>xed-utils</FILE> <FILE>xed-utils</FILE>
GBOOLEAN_TO_POINTER GBOOLEAN_TO_POINTER

26
docs/reference/xed.types
View File

@ -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

2
xed/Makefile.am
View File

@ -80,7 +80,7 @@ INST_H_FILES = \
xed-window-activatable.h xed-window-activatable.h
if !ENABLE_GVFS_METADATA if !ENABLE_GVFS_METADATA
INST_H_FILES += xed-metadata-manager.h NOINST_H_FILES += xed-metadata-manager.h
endif endif
headerdir = $(prefix)/include/xed headerdir = $(prefix)/include/xed

13
xed/xed-commands-file.c
View File

@ -289,14 +289,15 @@ xed_commands_load_location (XedWindow *window,
/** /**
* xed_commands_load_locations: * xed_commands_load_locations:
* @window: * @window: a #XedWindow
* @locations: (element-type GLib.File) (transfer none): * @locations: (element-type Gio.File): the locations to load
* @encoding: (allow-none): * @encoding: (allow-none): the #GtkSourceEncoding
* @line_pos: * @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 * GSList *
xed_commands_load_locations (XedWindow *window, xed_commands_load_locations (XedWindow *window,

8
xed/xed-document.c
View File

@ -832,7 +832,7 @@ xed_document_set_location (XedDocument *doc,
/** /**
* xed_document_get_uri_for_display: * xed_document_get_uri_for_display:
* @doc: * @doc: a #XedDocument
* *
* Note: this never returns %NULL. * Note: this never returns %NULL.
**/ **/
@ -857,7 +857,7 @@ xed_document_get_uri_for_display (XedDocument *doc)
/** /**
* xed_document_get_short_name_for_display: * xed_document_get_short_name_for_display:
* @doc: * @doc: a #XedDocument
* *
* Note: this never returns %NULL. * Note: this never returns %NULL.
**/ **/
@ -911,7 +911,7 @@ xed_document_get_content_type (XedDocument *doc)
/** /**
* xed_document_get_mime_type: * xed_document_get_mime_type:
* @doc: * @doc: a #XedDocument
* *
* Note: this never returns %NULL. * Note: this never returns %NULL.
**/ **/
@ -1461,7 +1461,7 @@ xed_document_set_metadata (XedDocument *doc,
* *
* Gets the metadata assigned to @key. * Gets the metadata assigned to @key.
* *
* Returns: the value assigned to @key. * Returns: the value assigned to @key. Free with g_free().
*/ */
gchar * gchar *
xed_document_get_metadata (XedDocument *doc, xed_document_get_metadata (XedDocument *doc,

33
xed/xed-encodings-combo-box.c
View File

@ -33,16 +33,14 @@
#include <config.h> #include <config.h>
#endif #endif
#include <glib/gi18n.h> #include "xed-encodings-combo-box.h"
#include <gtksourceview/gtksource.h>
#include <glib/gi18n.h>
#include "xed/xed-encodings-combo-box.h"
#include <xed/xed-encodings-dialog.h> #include <xed/xed-encodings-dialog.h>
#include "xed-settings.h" #include "xed-settings.h"
#include "xed-utils.h" #include "xed-utils.h"
#define ENCODING_KEY "Enconding"
#define XED_ENCODINGS_COMBO_BOX_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE ((object), \ #define XED_ENCODINGS_COMBO_BOX_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE ((object), \
XED_TYPE_ENCODINGS_COMBO_BOX, \ XED_TYPE_ENCODINGS_COMBO_BOX, \
XedEncodingsComboBoxPrivate)) XedEncodingsComboBoxPrivate))
@ -386,6 +384,17 @@ xed_encodings_combo_box_init (XedEncodingsComboBox *menu)
update_menu (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 * GtkWidget *
xed_encodings_combo_box_new (gboolean save_mode) xed_encodings_combo_box_new (gboolean save_mode)
{ {
@ -394,6 +403,13 @@ xed_encodings_combo_box_new (gboolean save_mode)
NULL); 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 * const GtkSourceEncoding *
xed_encodings_combo_box_get_selected_encoding (XedEncodingsComboBox *menu) 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: * xed_encodings_combo_box_set_selected_encoding:
* @menu: * @menu: a #XedEncodingsComboBox
* @encoding: (allow-none): * @encoding: the #GtkSourceEncoding
*
* Sets the selected encoding.
**/ **/
void void
xed_encodings_combo_box_set_selected_encoding (XedEncodingsComboBox *menu, xed_encodings_combo_box_set_selected_encoding (XedEncodingsComboBox *menu,
@ -428,6 +446,7 @@ xed_encodings_combo_box_set_selected_encoding (XedEncodingsComboBox *menu,
GtkTreeIter iter; GtkTreeIter iter;
GtkTreeModel *model; GtkTreeModel *model;
gboolean b; gboolean b;
g_return_if_fail (XED_IS_ENCODINGS_COMBO_BOX (menu)); g_return_if_fail (XED_IS_ENCODINGS_COMBO_BOX (menu));
g_return_if_fail (GTK_IS_COMBO_BOX (menu)); g_return_if_fail (GTK_IS_COMBO_BOX (menu));

2
xed/xed-encodings-combo-box.h
View File

@ -32,7 +32,7 @@
#ifndef __XED_ENCODINGS_COMBO_BOX_H__ #ifndef __XED_ENCODINGS_COMBO_BOX_H__
#define __XED_ENCODINGS_COMBO_BOX_H__ #define __XED_ENCODINGS_COMBO_BOX_H__
#include <gtk/gtk.h> #include <gtksourceview/gtksource.h>
G_BEGIN_DECLS G_BEGIN_DECLS

4
xed/xed-progress-info-bar.c
View File

@ -179,14 +179,14 @@ xed_progress_info_bar_new (const gchar *icon_name,
"has-cancel-button", has_cancel, "has-cancel-button", has_cancel,
NULL)); 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); xed_progress_info_bar_set_markup (bar, markup);
return GTK_WIDGET (bar); return GTK_WIDGET (bar);
} }
void void
xed_progress_info_bar_set_image (XedProgressInfoBar *bar, xed_progress_info_bar_set_icon_name (XedProgressInfoBar *bar,
const gchar *icon_name) const gchar *icon_name)
{ {
g_return_if_fail (XED_IS_PROGRESS_INFO_BAR (bar)); g_return_if_fail (XED_IS_PROGRESS_INFO_BAR (bar));

2
xed/xed-progress-info-bar.h
View File

@ -65,7 +65,7 @@ GtkWidget *xed_progress_info_bar_new (const gchar *icon_name,
const gchar *markup, const gchar *markup,
gboolean has_cancel); gboolean has_cancel);
void xed_progress_info_bar_set_image (XedProgressInfoBar *area, void xed_progress_info_bar_set_icon_name (XedProgressInfoBar *area,
const gchar *icon_name); const gchar *icon_name);
void xed_progress_info_bar_set_markup (XedProgressInfoBar *area, void xed_progress_info_bar_set_markup (XedProgressInfoBar *area,

2
xed/xed-statusbar.h
View File

@ -62,8 +62,6 @@ GType xed_statusbar_get_type (void) G_GNUC_CONST;
GtkWidget *xed_statusbar_new (void); GtkWidget *xed_statusbar_new (void);
/* FIXME: status is not defined in any .h */
#define XedStatus gint
void xed_statusbar_set_window_state (XedStatusbar *statusbar, void xed_statusbar_set_window_state (XedStatusbar *statusbar,
XedWindowState state, XedWindowState state,
gint num_of_errors); gint num_of_errors);