GNOME.org
 

[gtksourceview] Start moving docs inline

commit 592cbe11411e38202afa4482ae4ce4e0e9e514a9
Author: Paolo Borelli <pborelli gnome org>
Date:   Sun Dec 27 11:21:03 2009 +0100

    Start moving docs inline

 docs/reference/tmpl/buffer.sgml |  347 -------------------------
 docs/reference/tmpl/gutter.sgml |  171 ------------
 docs/reference/tmpl/iter.sgml   |   56 ----
 docs/reference/tmpl/mark.sgml   |   83 ------
 docs/reference/tmpl/view.sgml   |  544 ---------------------------------------
 gtksourceview/gtksourcebuffer.c |   23 ++-
 gtksourceview/gtksourcegutter.c |   32 +++
 gtksourceview/gtksourceiter.c   |   11 +-
 gtksourceview/gtksourcemark.c   |   31 ++-
 gtksourceview/gtksourceview.c   |   15 +-
 gtksourceview/gtksourceview.h   |   10 +-
 11 files changed, 108 insertions(+), 1215 deletions(-)
---
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index dfe2923..cd273e8 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourcebuffer.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourcebuffer.c
  *
  *  Copyright (C) 1999,2000,2001,2002 by:
  *          Mikael Hermansson <tyan linux se>
@@ -40,6 +40,25 @@
 #include "gtksourcestyleschememanager.h"
 #include "gtksourcestyle-private.h"
 
+/**
+ * SECTION:buffer
+ * @Short_description: Buffer object for #GtkSourceView
+ * @Title: GtkSourceBuffer
+ * @See_also: #GtkTextBuffer,#GtkSourceView
+ *
+ * The #GtkSourceBuffer object is the model for #GtkSourceView widgets.
+ * It extends the #GtkTextBuffer object by adding features useful to display
+ * and edit source code as syntax highlighting and bracket matching. It
+ * also implements support for undo/redo operations.
+ *
+ * To create a #GtkSourceBuffer use gtk_source_buffer_new() or
+ * gtk_source_buffer_new_with_language(). The second form is just a convenience
+ * function which allows you to initially set a #GtkSourceLanguage.
+ *
+ * By default highlighting is enabled, but you can disable it with
+ * gtk_source_buffer_set_highlight_syntax().
+ */
+
 /*
 #define ENABLE_DEBUG
 #define ENABLE_PROFILE
diff --git a/gtksourceview/gtksourcegutter.c b/gtksourceview/gtksourcegutter.c
index 3057f4c..ac861de 100644
--- a/gtksourceview/gtksourcegutter.c
+++ b/gtksourceview/gtksourcegutter.c
@@ -1,3 +1,4 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
 /*
  * gtksourcegutter.c
  * This file is part of gtksourceview
@@ -24,6 +25,37 @@
 #include "gtksourceview-i18n.h"
 #include "gtksourceview-marshal.h"
 
+/**
+ * SECTION:gutter
+ * @Short_description: Gutter object for #GtkSourceView
+ * @Title: GtkSourceGutter
+ * @See_also:#GtkSourceView
+ *
+ * The #GtkSourceGutter object represents the left and right gutters of the text
+ * view. It is used by #GtkSourceView to draw the line numbers and category
+ * marks that might be present on a line. By packing additional #GtkCellRenderer
+ * objects in the gutter, you can extend the gutter with your own custom 
+ * drawings.
+ *
+ * The gutter works very much the same way as cells rendered in a #GtkTreeView.
+ * The concept is similar, with the exception that the gutter does not have an
+ * underlying #GtkTreeModel. Instead, you should use
+ * #gtk_source_gutter_set_cell_data_func to set a callback to fill in any of the
+ * cell renderers properties, given the line for which the cell is to be
+ * rendered. Renderers are inserted into the gutter at a certain position. The
+ * builtin line number renderer is at position 
+
+ * #GTK_SOURCE_VIEW_GUTTER_POSITION_LINES (-30) and the marks renderer is at
+ * #GTK_SOURCE_VIEW_GUTTER_POSITION_MARKS (-20). You can use these values to
+ * position custom renderers accordingly. The width of a cell renderer can be
+ * specified as either fixed (using
+
+ * #gtk_cell_renderer_set_fixed_size) or dynamic, in which case you
+ * <emphasis>must</emphasis> set #gtk_source_gutter_set_cell_size_func. This
+ * callback is used to set the properties of the renderer such that
+ * #gtk_cell_renderer_get_size yields the maximum width of the cell.
+ */
+
 #define GTK_SOURCE_GUTTER_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE((object), GTK_TYPE_SOURCE_GUTTER, GtkSourceGutterPrivate))
 
 /* Properties */
diff --git a/gtksourceview/gtksourceiter.c b/gtksourceview/gtksourceiter.c
index 9570ccc..6a9eb6f 100644
--- a/gtksourceview/gtksourceiter.c
+++ b/gtksourceview/gtksourceiter.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
- *  gtksourceiter.h
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourceiter.c
  *
  *  Copyright (C) 2000 - 2005 Paolo Maggi
  *  Copyright (C) 2002, 2003 Jeroen Zwartepoorte
@@ -30,6 +30,13 @@
 #include <string.h>
 #include "gtksourceiter.h"
 
+/**
+ * SECTION:iter
+ * @Short_description: Improved search support in a #GtkSourceBuffer
+ * @Title: GtkSourceIter
+ * @See_also: #GtkTextIter
+ */
+
 #define GTK_TEXT_UNKNOWN_CHAR 0xFFFC
 
 /* this function acts like g_utf8_offset_to_pointer() except that if it finds a
diff --git a/gtksourceview/gtksourcemark.c b/gtksourceview/gtksourcemark.c
index 6181ff9..9230fd0 100644
--- a/gtksourceview/gtksourcemark.c
+++ b/gtksourceview/gtksourcemark.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourcebuffer.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourcemark.c
  *
  *  Copyright (C) 2007 by:
  *		Johannes Schmid <jhs gnome org>
@@ -21,8 +21,27 @@
 
 #include "gtksourcemark.h"
 #include "gtksourcebuffer.h"
+#include "gtksourceview-i18n.h"
 
-#include <glib/gi18n.h>
+/**
+ * SECTION:mark
+ * @Short_description: mark object for #GtkSourceBuffer
+ * @Title: GtkSourceMark
+ * @See_also: #GtkSourceBuffer
+ *
+ * A #GtkSourceMark marks a position in the text where you want to display
+ * additional info. It is based on #GtkTextMark and thus is still valid after
+ * the text has changed though its position may change.
+ *
+ * #GtkSourceMarks are organised in categories which you have to set when you
+ * create the mark. Each category can have a pixbuf and a priority associated
+ * using #gtk_source_view_set_mark_category_pixbuf and
+ * #gtk_source_view_set_mark_category_priority. The pixbuf will be displayed in
+ * the margin at the line where the mark residents if the
+ * #GtkSourceView::show-line-marks property is set to TRUE. If there are
+ * multiple marks in the same line, the pixbufs will be drawn on top of each
+ * other. The mark with the highest priority will be drawn on top.
+ */
 
 enum
 {
@@ -112,8 +131,8 @@ gtk_source_mark_class_init (GtkSourceMarkClass *klass)
 	/**
 	 * GtkSourceMark:category:
 	 *
-	 * The category of the #GtkSourceMark, classified the mark and control
-	 * what pixbuf is used and with which priority it is drawn.
+	 * The category of the #GtkSourceMark, classifies the mark and controls
+	 * which pixbuf is used and with which priority it is drawn.
 	 */
 	g_object_class_install_property (object_class,
 					 PROP_CATEGORY,
@@ -122,7 +141,7 @@ gtk_source_mark_class_init (GtkSourceMarkClass *klass)
 							      _("The mark category"),
 							      NULL,
 							      G_PARAM_READABLE | G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
-	
+
 	g_type_class_add_private (object_class, sizeof (GtkSourceMarkPrivate));
 }
 
diff --git a/gtksourceview/gtksourceview.c b/gtksourceview/gtksourceview.c
index 1a3bc19..54f4bf3 100644
--- a/gtksourceview/gtksourceview.c
+++ b/gtksourceview/gtksourceview.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourceview.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourceview.c
  *
  *  Copyright (C) 2001 - Mikael Hermansson <tyan linux se> and
  *  Chris Phelps <chicane reninet com>
@@ -43,6 +43,17 @@
 #include "gtksourcecompletionutils.h"
 #include "gtksourcegutter-private.h"
 
+/**
+ * SECTION:view
+ * @Short_description: The view object
+ * @Title: GtkSourceView
+ * @See_also: #GtkTextView,#GtkSourceBuffer
+ *
+ * GtkSourceView is the main object of the gtksourceview library. It provides
+ * a text view which syntax highlighting, undo/redo and text marks. Use a 
+ * #GtkSourceBuffer to display text with a GtkSourceView.
+ */
+
 /*
 #define ENABLE_DEBUG
 */
diff --git a/gtksourceview/gtksourceview.h b/gtksourceview/gtksourceview.h
index bfbdeeb..e7a5672 100644
--- a/gtksourceview/gtksourceview.h
+++ b/gtksourceview/gtksourceview.h
@@ -104,8 +104,6 @@ typedef enum
  *
  * GtkSourceDrawSpacesFlags determine what kind of spaces whould be drawn.
  */
-/* TODO: it would be nice to have flags to specify to draw
- * just leading/trailing whitespaces */
 typedef enum
 {
 	GTK_SOURCE_DRAW_SPACES_SPACE      = 1 << 0,
@@ -215,6 +213,14 @@ gboolean         gtk_source_view_get_mark_category_background
 							 const gchar     *category,
 							 GdkColor        *dest);
 
+/**
+ * GtkSourceViewMarkTooltipFunc:
+ * @mark: the #GtkSourceMark
+ * @user_data: user data pointer which was passed to gtk_source_view_set_mark_category_tooltip_func()
+ *
+ * Function type for setting up a tooltip for #GtkSourceMark.
+ * Returns: a newly-allocated string that is going to be shown as tooltip text.
+ */
 typedef gchar *  (*GtkSourceViewMarkTooltipFunc)	(GtkSourceMark	*mark,
 							 gpointer	 user_data);
 void             gtk_source_view_set_mark_category_tooltip_func
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]