Doc fixes

2008-12-28  Matthias Clasen  <mclasen@redhat.com>

        * gtk/gtkimmodule.c:
        * gtk/gtkseparatortoolitem.c: Doc fixes

        * gtk/gtkfontsel.c: Merge docs inline.


svn path=/trunk/; revision=21957

ChangeLog

@@ -1,5 +1,9 @@
 2008-12-28  Matthias Clasen  <mclasen@redhat.com>
 
+	* gtk/gtkimmodule.c:
+	* gtk/gtkseparatortoolitem.c: Doc fixes
+
+	* gtk/gtkfontsel.c:
 	* gtk/gtkeditable.c: Merge docs inline.
 
 2008-12-28  Matthias Clasen  <mclasen@redhat.com>

gtk/gtkfontsel.c

@@ -538,6 +538,13 @@ gtk_font_selection_init (GtkFontSelection *fontsel)
   gtk_widget_pop_composite_child();
 }
 
+/**
+ * gtk_font_selection_new:
+ *
+ * Creates a new #GtkFontSelection.
+ *
+ * Return value: a n ew #GtkFontSelection
+ */
 GtkWidget *
 gtk_font_selection_new (void)
 {
@@ -1129,10 +1136,10 @@ gtk_font_selection_get_font_internal (GtkFontSelection *fontsel)
  * This returns the #GtkTreeView that lists font families, for
  * example, 'Sans', 'Serif', etc.
  * 
- * Return value: A #GtkWidget. 
+ * Return value: A #GtkWidget that is part of @fontsel
  *
  * Since: 2.14
- **/
+ */
 GtkWidget *
 gtk_font_selection_get_family_list (GtkFontSelection *fontsel)
 {
@@ -1148,10 +1155,10 @@ gtk_font_selection_get_family_list (GtkFontSelection *fontsel)
  * This returns the #GtkTreeView which lists all styles available for
  * the selected font. For example, 'Regular', 'Bold', etc.
  * 
- * Return value: A #GtkWidget. 
+ * Return value: A #GtkWidget that is part of @fontsel
  *
  * Since: 2.14
- **/
+ */
 GtkWidget *
 gtk_font_selection_get_face_list (GtkFontSelection *fontsel)
 {
@@ -1167,10 +1174,10 @@ gtk_font_selection_get_face_list (GtkFontSelection *fontsel)
  * This returns the #GtkEntry used to allow the user to edit the font
  * number manually instead of selecting it from the list of font sizes. 
  * 
- * Return value: A #GtkWidget. 
+ * Return value: A #GtkWidget that is part of @fontsel
  *
  * Since: 2.14
- **/
+ */
 GtkWidget *
 gtk_font_selection_get_size_entry (GtkFontSelection *fontsel)
 {
@@ -1185,10 +1192,10 @@ gtk_font_selection_get_size_entry (GtkFontSelection *fontsel)
  *
  * This returns the #GtkTreeeView used to list font sizes. 
  * 
- * Return value: A #GtkWidget. 
+ * Return value: A #GtkWidget that is part of @fontsel
  *
  * Since: 2.14
- **/
+ */
 GtkWidget *
 gtk_font_selection_get_size_list (GtkFontSelection *fontsel)
 {
@@ -1203,10 +1210,10 @@ gtk_font_selection_get_size_list (GtkFontSelection *fontsel)
  * 
  * This returns the #GtkEntry used to display the font as a preview.
  *
- * Return value: A #GtkWidget. 
+ * Return value: A #GtkWidget that is part of @fontsel
  *
  * Since: 2.14
- **/
+ */
 GtkWidget *
 gtk_font_selection_get_preview_entry (GtkFontSelection *fontsel)
 {
@@ -1222,10 +1229,12 @@ gtk_font_selection_get_preview_entry (GtkFontSelection *fontsel)
  * Gets the #PangoFontFamily representing the selected font family.
  *
  * Return value: A #PangoFontFamily representing the selected font
- * family. Font families are a collection of font faces.
+ *     family. Font families are a collection of font faces. The 
+ *     returned object is owned by @fontsel and must not be modified 
+ *     or freed.
  *
  * Since: 2.14
- **/
+ */
 PangoFontFamily *
 gtk_font_selection_get_family (GtkFontSelection *fontsel)
 {
@@ -1241,11 +1250,12 @@ gtk_font_selection_get_family (GtkFontSelection *fontsel)
  * Gets the #PangoFontFace representing the selected font group
  * details (i.e. family, slant, weight, width, etc).   
  *
- * Return value: A #PangoFontFace representing the selected font group
+ * Return value: A #PangoFontFace representing the selected font 
- *     details 
+ *     group details. The returned object is owned by @fontsel and
+ *     must not be modified or freed. 
  *
  * Since: 2.14
- **/
+ */
 PangoFontFace *
 gtk_font_selection_get_face (GtkFontSelection *fontsel)
 {
@@ -1260,8 +1270,8 @@ gtk_font_selection_get_face (GtkFontSelection *fontsel)
  * 
  * The selected font size.
  *
- * Return value: A #gint representing the font size selected, or -1
+ * Return value: A n integer representing the selected font size, 
- * if not.
+ *     or -1 if no font size is selected.
  *
  * Since: 2.14
  **/
@@ -1277,10 +1287,12 @@ gtk_font_selection_get_size (GtkFontSelection *fontsel)
  * gtk_font_selection_get_font:
  * @fontsel: a #GtkFontSelection
  *
+ * Gets the currently-selected font.
+ * 
  * Return value: A #GdkFont.
  *
  * Deprecated: 2.0: Use gtk_font_selection_get_font_name() instead.
- **/
+ */
 GdkFont *
 gtk_font_selection_get_font (GtkFontSelection *fontsel)
 {
@@ -1293,16 +1305,18 @@ gtk_font_selection_get_font (GtkFontSelection *fontsel)
  * gtk_font_selection_get_font_name:
  * @fontsel: a #GtkFontSelection
  * 
- * Gets the currently-selected font name.  Note that this can be a different
+ * Gets the currently-selected font name. 
- * string than what you set with gtk_font_selection_set_font_name(), as
+ *
- * the font selection widget may normalize font names and thus return a string
+ * Note that this can be a different string than what you set with 
- * with a different structure.  For example, "Helvetica Italic Bold 12" could be
+ * gtk_font_selection_set_font_name(), as the font selection widget may 
- * normalized to "Helvetica Bold Italic 12".  Use pango_font_description_equal()
+ * normalize font names and thus return a string with a different structure. 
+ * For example, "Helvetica Italic Bold 12" could be normalized to 
+ * "Helvetica Bold Italic 12". Use pango_font_description_equal()
  * if you want to compare two font descriptions.
  * 
- * Return value: A string with the name of the current font, or #NULL if no font
+ * Return value: A string with the name of the current font, or %NULL if 
- * is selected.  You must free this string with g_free().
+ *     no font is selected. You must free this string with g_free().
- **/
+ */
 gchar *
 gtk_font_selection_get_font_name (GtkFontSelection *fontsel)
 {
@@ -1327,14 +1341,16 @@ gtk_font_selection_get_font_name (GtkFontSelection *fontsel)
  * @fontsel: a #GtkFontSelection
  * @fontname: a font name like "Helvetica 12" or "Times Bold 18"
  * 
- * Sets the currently-selected font.  Note that the @fontsel needs to know the
+ * Sets the currently-selected font. 
- * screen in which it will appear for this to work; this can be guaranteed by
- * simply making sure that the @fontsel is inserted in a toplevel window before
- * you call this function.
  *
- * Return value: #TRUE if the font could be set successfully; #FALSE if no such
+ * Note that the @fontsel needs to know the screen in which it will appear 
- * font exists or if the @fontsel doesn't belong to a particular screen yet.
+ * for this to work; this can be guaranteed by simply making sure that the 
- **/
+ * @fontsel is inserted in a toplevel window before you call this function.
+ * 
+ * Return value: %TRUE if the font could be set successfully; %FALSE if no 
+ *     such font exists or if the @fontsel doesn't belong to a particular 
+ *     screen yet.
+ */
 gboolean
 gtk_font_selection_set_font_name (GtkFontSelection *fontsel,
 				  const gchar      *fontname)
@@ -1440,13 +1456,12 @@ gtk_font_selection_set_font_name (GtkFontSelection *fontsel,
  * gtk_font_selection_get_preview_text:
  * @fontsel: a #GtkFontSelection
  *
- * The text returned is the preview text used to show how the selected
+ * Gets the text displayed in the preview area.
- * font looks.  
  * 
- * Return value: pointer to the preview text string. This string
+ * Return value: the text displayed in the preview area. 
- * points to internally allocated storage in the widget and must not
+ *     This string is owned by the widget and should not be 
- * be freed, modified or stored. 
+ *     modified or freed 
- **/
+ */
 G_CONST_RETURN gchar*
 gtk_font_selection_get_preview_text (GtkFontSelection *fontsel)
 {
@@ -1459,10 +1474,11 @@ gtk_font_selection_get_preview_text (GtkFontSelection *fontsel)
 /**
  * gtk_font_selection_set_preview_text:
  * @fontsel: a #GtkFontSelection
- * @text: a pointer to a string
+ * @text: the text to display in the preview area 
  *
+ * Sets the text displayed in the preview area.
  * The @text is used to show how the selected font looks.
- **/
+ */
 void
 gtk_font_selection_set_preview_text  (GtkFontSelection *fontsel,
 				      const gchar      *text)
@@ -1655,16 +1671,18 @@ gtk_font_selection_dialog_buildable_get_internal_child (GtkBuildable *buildable,
  * gtk_font_selection_dialog_get_font_name:
  * @fsd: a #GtkFontSelectionDialog
  * 
- * Gets the currently-selected font name.  Note that this can be a different
+ * Gets the currently-selected font name.
- * string than what you set with gtk_font_selection_dialog_set_font_name(), as
+ *
- * the font selection widget may normalize font names and thus return a string
+ * Note that this can be a different string than what you set with 
- * with a different structure.  For example, "Helvetica Italic Bold 12" could be
+ * gtk_font_selection_dialog_set_font_name(), as the font selection widget
- * normalized to "Helvetica Bold Italic 12".  Use pango_font_description_equal()
+ * may normalize font names and thus return a string with a different 
+ * structure. For example, "Helvetica Italic Bold 12" could be normalized 
+ * to "Helvetica Bold Italic 12".  Use pango_font_description_equal()
  * if you want to compare two font descriptions.
  * 
- * Return value: A string with the name of the current font, or #NULL if no font
+ * Return value: A string with the name of the current font, or %NULL if no 
- * is selected.  You must free this string with g_free().
+ *     font is selected. You must free this string with g_free().
- **/
+ */
 gchar*
 gtk_font_selection_dialog_get_font_name (GtkFontSelectionDialog *fsd)
 {
@@ -1698,7 +1716,7 @@ gtk_font_selection_dialog_get_font (GtkFontSelectionDialog *fsd)
  * Sets the currently selected font. 
  * 
  * Return value: %TRUE if the font selected in @fsd is now the
- * @fontname specified. %FALSE otherwise. 
+ *     @fontname specified, %FALSE otherwise. 
  */
 gboolean
 gtk_font_selection_dialog_set_font_name (GtkFontSelectionDialog *fsd,
@@ -1733,7 +1751,7 @@ gtk_font_selection_dialog_get_preview_text (GtkFontSelectionDialog *fsd)
  * gtk_font_selection_dialog_set_preview_text:
  * @fsd: a #GtkFontSelectionDialog
  * @text: a pointer to a string
-
+ *
  * The @text is used to show how the selected font looks.
  */
 void

gtk/gtkimmodule.c

@@ -55,10 +55,8 @@
  * GtkIMContextInfo:
  * @context_id: The unique identification string of the input method.
  * @context_name: The human-readable name of the input method.
- * @domain: Translation domain to be used with
+ * @domain: Translation domain to be used with dgettext()
- *   <function>dgettext&lpar;&rpar;</function>.
+ * @domain_dirname: Name of locale directory for use with bindtextdomain()
- * @domain_dirname: Name of locale directory for use with
- *   <function>bindtextdomain&lpar;&rpar;</function>.
  * @default_locales: A colon-separated list of locales where this input method
  *   should be the default. The asterisk "*" sets the default for all locales.
  *
@@ -513,7 +511,7 @@ compare_gtkimcontextinfo_name(const GtkIMContextInfo **a,
  * @n_contexts: the length of the array stored in @contexts
  * 
  * List all available types of input method context
- **/
+ */
 void
 _gtk_im_module_list (const GtkIMContextInfo ***contexts,
 		     guint                    *n_contexts)
@@ -592,7 +590,7 @@ _gtk_im_module_list (const GtkIMContextInfo ***contexts,
  * 
  * Return value: a newly created input context of or @context_id, or
  *     if that could not be created, a newly created GtkIMContextSimple.
- **/
+ */
 GtkIMContext *
 _gtk_im_module_create (const gchar *context_id)
 {
@@ -660,7 +658,7 @@ match_locale (const gchar *locale,
  * for the given window.
  * 
  * Return value: the context ID (will never be %NULL)
- **/
+ */
 const gchar *
 _gtk_im_module_get_default_context_id (GdkWindow *client_window)
 {

gtk/gtkseparatortoolitem.c

@@ -221,7 +221,7 @@ gtk_separator_tool_item_expose (GtkWidget      *widget,
  * Return value: the new #GtkSeparatorToolItem
  * 
  * Since: 2.4
- **/
+ */
 GtkToolItem *
 gtk_separator_tool_item_new (void)
 {
@@ -237,13 +237,13 @@ gtk_separator_tool_item_new (void)
  * gtk_separator_tool_item_get_draw:
  * @item: a #GtkSeparatorToolItem 
  * 
- * Returns whether @separator_tool_item is drawn as a
+ * Returns whether @item is drawn as a line, or just blank. 
- * line, or just blank. See gtk_separator_tool_item_set_draw().
+ * See gtk_separator_tool_item_set_draw().
  * 
- * Return value: #TRUE if @separator_tool_item is drawn as a line, or just blank.
+ * Return value: %TRUE if @item is drawn as a line, or just blank.
  * 
  * Since: 2.4
- **/
+ */
 gboolean
 gtk_separator_tool_item_get_draw (GtkSeparatorToolItem *item)
 {
@@ -255,14 +255,14 @@ gtk_separator_tool_item_get_draw (GtkSeparatorToolItem *item)
 /**
  * gtk_separator_tool_item_set_draw:
  * @item: a #GtkSeparatorToolItem
- * @draw: whether @separator_tool_item is drawn as a vertical line
+ * @draw: whether @item is drawn as a vertical line
  * 
- * When @separator_tool_items is drawn as a vertical line, or just blank.
+ * Whether @item is drawn as a vertical line, or just blank.
- * Setting this #FALSE along with gtk_tool_item_set_expand() is useful
+ * Setting this to %FALSE along with gtk_tool_item_set_expand() is useful
  * to create an item that forces following items to the end of the toolbar.
  * 
  * Since: 2.4
- **/
+ */
 void
 gtk_separator_tool_item_set_draw (GtkSeparatorToolItem *item,
 				  gboolean              draw)