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

59
docs/reference/Makefile.am
View File

@ -6,40 +6,29 @@
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-close-confirmation-dialog.h \
xed-dirs.h \
xed-commands.h \
xed-documents-panel.h \
xed-io-error-info-bar.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= \
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

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-activatable.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-message-bus.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-print-job-preview.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-tab.xml"/>
<xi:include href="xml/xed-view.xml"/>
@ -29,7 +29,19 @@
<xi:include href="xml/xed-convert.xml"/>
<xi:include href="xml/xed-debug.xml"/>
<xi:include href="xml/xed-help.xml"/>
<xi:include href="xml/xed-metadata-manager.xml"/>
<xi:include href="xml/xed-utils.xml"/>
</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>

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

@ -1,14 +1,13 @@
<SECTION>
<FILE>xed-app</FILE>
XedAppPrivate
<TITLE>XedApp</TITLE>
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
<SUBSECTION Standard>
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
<SUBSECTION Standard>
XED_DOCUMENT
XED_IS_DOCUMENT
@ -63,21 +63,20 @@ XED_DOCUMENT_GET_CLASS
</SECTION>
<SECTION>
<FILE>xed-encodings-option-menu</FILE>
XedEncodingsOptionMenuPrivate
<FILE>xed-encodings-combo-box</FILE>
<TITLE>XedEncodingsOptionMenu</TITLE>
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
<SUBSECTION Standard>
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
</SECTION>
<SECTION>
@ -264,33 +263,30 @@ XED_PRINT_JOB_GET_CLASS
</SECTION>
<SECTION>
<FILE>xed-progress-message-area</FILE>
XedProgressMessageAreaPrivate
<TITLE>XedProgressMessageArea</TITLE>
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
<FILE>xed-progress-info-bar</FILE>
<TITLE>XedProgressInfoBar</TITLE>
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
<SUBSECTION Standard>
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
</SECTION>
<SECTION>
<FILE>xed-statusbar</FILE>
XedStatusbarPrivate
<TITLE>XedStatusbar</TITLE>
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
</SECTION>
<SECTION>
<FILE>xed-metadata-manager</FILE>
xed_metadata_manager_shutdown
xed_metadata_manager_get
xed_metadata_manager_set
</SECTION>
<SECTION>
<FILE>xed-utils</FILE>
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
if !ENABLE_GVFS_METADATA
INST_H_FILES += xed-metadata-manager.h
NOINST_H_FILES += xed-metadata-manager.h
endif
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:
* @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,

8
xed/xed-document.c
View File

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

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

@ -33,16 +33,14 @@
#include <config.h>
#endif
#include <glib/gi18n.h>
#include <gtksourceview/gtksource.h>
#include "xed-encodings-combo-box.h"
#include <glib/gi18n.h>
#include "xed/xed-encodings-combo-box.h"
#include <xed/xed-encodings-dialog.h>
#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));

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

@ -32,7 +32,7 @@
#ifndef __XED_ENCODINGS_COMBO_BOX_H__
#define __XED_ENCODINGS_COMBO_BOX_H__
#include <gtk/gtk.h>
#include <gtksourceview/gtksource.h>
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,
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,
xed_progress_info_bar_set_icon_name (XedProgressInfoBar *bar,
const gchar *icon_name)
{
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,
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);
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);
/* 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);