Doc updates.

ChangeLog

@@ -1,5 +1,17 @@
 2002-05-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment.
+
+	* gdk/x11/gdkdisplay-x11.c (gdk_open_display): 
+	* gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): 
+	* gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): 
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen):
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): 
+	* gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): 
+	* gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document.
+
 	* gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix.
 
 	* gtk/gtkwidget.c (gtk_widget_class_init): Correct the

ChangeLog.pre-2-10

@@ -1,5 +1,17 @@
 2002-05-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment.
+
+	* gdk/x11/gdkdisplay-x11.c (gdk_open_display): 
+	* gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): 
+	* gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): 
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen):
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): 
+	* gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): 
+	* gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document.
+
 	* gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix.
 
 	* gtk/gtkwidget.c (gtk_widget_class_init): Correct the

ChangeLog.pre-2-2

@@ -1,5 +1,17 @@
 2002-05-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment.
+
+	* gdk/x11/gdkdisplay-x11.c (gdk_open_display): 
+	* gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): 
+	* gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): 
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen):
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): 
+	* gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): 
+	* gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document.
+
 	* gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix.
 
 	* gtk/gtkwidget.c (gtk_widget_class_init): Correct the

ChangeLog.pre-2-4

@@ -1,5 +1,17 @@
 2002-05-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment.
+
+	* gdk/x11/gdkdisplay-x11.c (gdk_open_display): 
+	* gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): 
+	* gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): 
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen):
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): 
+	* gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): 
+	* gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document.
+
 	* gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix.
 
 	* gtk/gtkwidget.c (gtk_widget_class_init): Correct the

ChangeLog.pre-2-6

@@ -1,5 +1,17 @@
 2002-05-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment.
+
+	* gdk/x11/gdkdisplay-x11.c (gdk_open_display): 
+	* gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): 
+	* gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): 
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen):
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): 
+	* gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): 
+	* gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document.
+
 	* gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix.
 
 	* gtk/gtkwidget.c (gtk_widget_class_init): Correct the

ChangeLog.pre-2-8

@@ -1,5 +1,17 @@
 2002-05-02  Matthias Clasen  <maclas@gmx.de>
 
+	* gdk/gdkscreen.c (gdk_screen_get_monitor_at_window): Fix doc comment.
+
+	* gdk/x11/gdkdisplay-x11.c (gdk_open_display): 
+	* gdk/x11/gdkkeys-x11.c (gdk_keymap_get_default): 
+	* gdk/x11/gdkfont-x11.c (gdk_fontset_load_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_from_description_for_display): 
+	* gdk/x11/gdkfont-x11.c (gdk_font_load_for_display): 
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_xscreen):
+	* gdk/x11/gdkscreen-x11.c (gdk_x11_screen_get_screen_number): 
+	* gdk/x11/gdkdisplay-x11.c (gdk_x11_display_get_xdisplay): 
+	* gdk/x11/gdkdnd-x11.c (gdk_drag_get_protocol_for_display): Document.
+
 	* gtk/gtknotebook.c (gtk_notebook_set_show_border): Typo fix.
 
 	* gtk/gtkwidget.c (gtk_widget_class_init): Correct the

docs/reference/ChangeLog

@@ -1,4 +1,14 @@
-2002-05-02  Matthias Clasen  <maclas@gmx.de>
+2002-05-03  Matthias Clasen  <maclas@gmx.de>
+
+ 	* gdk/gdk-sections.txt: Remove gdk_screen_use_virtual_screen.
+
+	* gdk/tmpl/gdkscreen.sgml: Updates.
+
+	* gdk/tmpl/gdkdisplay.sgml: Document GdkDisplay.
+
+	* gdk/tmpl/x_interaction.sgml: Document GDK_DISPLAY_XDISPLAY,
+	GDK_SCREEN_XDISPLAY, GDK_SCREEN_XSCREEN, GDK_SCREEN_XNUMBER,
+	gdk_font_lookup_for_display.
 
 	* gdk/Makefile.am (GTKDOC_CFLAGS, GTKDOC_LIBS): set these. 
 

docs/reference/gdk/gdk-sections.txt

@@ -167,7 +167,6 @@ gdk_screen_get_height_mm
 gdk_screen_close
 gdk_screen_list_visuals
 gdk_screen_get_toplevel_windows
-gdk_screen_use_virtual_screen
 gdk_screen_get_n_monitors
 gdk_screen_get_monitor_geometry
 gdk_screen_get_monitor_at_point

docs/reference/gdk/tmpl/gdkdisplay.sgml

@@ -30,10 +30,10 @@ controls the keyboard/mouse pointer grabs and a set of <type>GdkScreen</type>s
 
 <!-- ##### STRUCT GdkDisplay ##### -->
 <para>
-
+The <structname>GdkDisplay</structname> struct is the GDK representation
+of an X display. All its fields are private and should not be accessed directly. 
 </para>
 
-@parent_instance: 
 
 <!-- ##### FUNCTION gdk_open_display ##### -->
 <para>

docs/reference/gdk/tmpl/gdkscreen.sgml

@@ -24,12 +24,10 @@ form a large screen area.
 
 <!-- ##### STRUCT GdkScreen ##### -->
 <para>
-This is a currently just a placeholder typedef for the first argument of 
+The <structname>GdkScreen</structname> struct is the GDK representation of a
-the @window_at_pointer function in #GdkPointerHooks. It will be used
+ physical screen. All its fields are private and should not be accessed directly. 
-when GDK gets multihead support. 
 </para>
 
-@parent_instance: 
 
 <!-- ##### FUNCTION gdk_screen_get_default_colormap ##### -->
 <para>
@@ -185,15 +183,6 @@ when GDK gets multihead support.
 @Returns: 
 
 
-<!-- ##### FUNCTION gdk_screen_use_virtual_screen ##### -->
-<para>
-
-</para>
-
-@screen: 
-@Returns: 
-
-
 <!-- ##### FUNCTION gdk_screen_get_n_monitors ##### -->
 <para>
 

docs/reference/gdk/tmpl/x_interaction.sgml

@@ -78,10 +78,10 @@ Returns the X pixmap belonging to a #GdkPixmap.
 
 <!-- ##### MACRO GDK_DISPLAY_XDISPLAY ##### -->
 <para>
-
+Returns the display of a #GdkDisplay.
 </para>
 
-@display: 
+@display: a #GdkDisplay.
 
 
 <!-- ##### MACRO GDK_DRAWABLE_XDISPLAY ##### -->
@@ -149,26 +149,30 @@ Returns the X colormap belonging to a #GdkColormap.
 
 <!-- ##### MACRO GDK_SCREEN_XDISPLAY ##### -->
 <para>
-
+Returns the display of a #GdkScreen.
 </para>
 
-@screen: 
+@screen: a #GdkScreen.
+@Returns: an Xlib <type>Display*</type>.
 
 
 <!-- ##### MACRO GDK_SCREEN_XNUMBER ##### -->
 <para>
-
+Returns the index of a #GdkScreen.
 </para>
 
-@screen: 
+@screen: a #GdkScreen
+@Returns: the position of @screen among the screens of
+  its display.
 
 
 <!-- ##### MACRO GDK_SCREEN_XSCREEN ##### -->
 <para>
-
+Returns the screen of a #GdkScreen.
 </para>
 
-@screen: 
+@screen: a #GdkScreen
+@Returns: an Xlib <type>Screen*</type>.
 
 
 <!-- ##### MACRO GDK_VISUAL_XVISUAL ##### -->
@@ -370,7 +374,7 @@ a #GdkWindow or a #GdkFont.
 
 <!-- ##### MACRO gdk_font_lookup ##### -->
 <para>
-Obtains the #GdkFont for the given Xlib pixmap ID, or %NULL if no #GdkPixmap has
+Obtains the #GdkFont for the given Xlib font ID, or %NULL if no #GdkFont has
 been created for @xid.
 </para>
 
@@ -379,7 +383,8 @@ been created for @xid.
 
 <!-- ##### MACRO gdk_font_lookup_for_display ##### -->
 <para>
-
+Obtains the #GdkFont for the given Xlib font ID on @display, or %NULL if no
+#GdkFont has been created for @xid.
 </para>
 
 @display: 

gdk/gdkscreen.c

@@ -317,14 +317,13 @@ gdk_screen_get_monitor_at_point (GdkScreen *screen,
 }
 
 /**
- * gdk_screen_get_monitor_num_at_window:
+ * gdk_screen_get_monitor_at_window:
- * @screen : a #GdkScreen.
+ * @screen: a #GdkScreen.
- * @anid : a #GdkDrawable ID.
+ * @window: a #GdkWindow
+ * @returns: the monitor number in which most of @window is located.
  *
- * Returns the monitor number in which the largest area of the bounding rectangle
+ * Returns the number of the monitor in which the largest area of the bounding rectangle
- * of @anid resides. 
+ * of @window resides. 
- *
- * Returns: the monitor number in which most of @anid is located.
  **/
 gint 
 gdk_screen_get_monitor_at_window (GdkScreen      *screen,

gdk/x11/gdkdisplay-x11.c

@@ -215,6 +215,14 @@ init_xinerama_support (GdkScreen * screen)
   screen_x11->monitors[0].height = HeightOfScreen (screen_x11->xscreen);
 }
 
+/**
+ * gdk_open_display:
+ * @display_name: the name of the display to open
+ * @returns: a #GdkDisplay, or %NULL if the display
+ *  could not be opened.
+ *
+ * Opens a display.
+ */
 GdkDisplay *
 gdk_open_display (const gchar *display_name)
 {
@@ -634,8 +642,17 @@ _gdk_x11_display_screen_for_xrootwin (GdkDisplay *display,
   return NULL;
 }
 
+/**
+ * gdk_x11_display_get_xdisplay:
+ * @display: a #GdkDisplay
+ * @returns: an X display.
+ *
+ * Returns the X display of a #GdkDisplay.
+ */
 Display *
 gdk_x11_display_get_xdisplay (GdkDisplay  *display)
 {
   return GDK_DISPLAY_X11 (display)->xdisplay;
 }
+
+

gdk/x11/gdkdnd-x11.c

@@ -2715,6 +2715,17 @@ gdk_drag_begin (GdkWindow     *window,
   return new_context;
 }
 
+/**
+ * gdk_drag_get_protocol_for_display:
+ * @display: the #GdkDisplay where the destination window resides
+ * @xid: the X id of the destination window.
+ * @protocol: location where the supported DND protocol is returned.
+ * @returns: the X id of the window where the drop should happen. This 
+ *     may be @xid or the X id of a proxy window, or None if @xid doesn't
+ *     support Drag and Drop.
+ *
+ * Finds out the DND protocol supported by a window.
+ */ 
 guint32
 gdk_drag_get_protocol_for_display (GdkDisplay      *display,
 				   guint32          xid,

gdk/x11/gdkfont-x11.c

@@ -162,6 +162,17 @@ gdk_font_hash_lookup (GdkDisplay  *display,
     }
 }
 
+/**
+ * gdk_font_load_for_display:
+ * @display: a #GdkDisplay
+ * @font_name: a XLFD describing the font to load.
+ * @returns: a #GdkFont, or %NULL if the font could not be loaded.
+ *
+ * Loads a font for use on @display.
+ *
+ * The font may be newly loaded or looked up the font in a cache. 
+ * You should make no assumptions about the initial reference count.
+ */
 GdkFont *
 gdk_font_load_for_display (GdkDisplay  *display, 
 			   const gchar *font_name)
@@ -254,6 +265,20 @@ gdk_font_charset_for_locale (void)
     return g_strdup ("iso8859-1");
 };
 
+/**
+ * gdk_font_from_description_for_display:
+ * @display: a #GdkDisplay
+ * @font_desc: a #PangoFontDescription.
+ * 
+ * Loads a #GdkFont based on a Pango font description for use on @display. 
+ * This font will only be an approximation of the Pango font, and
+ * internationalization will not be handled correctly. This function
+ * should only be used for legacy code that cannot be easily converted
+ * to use Pango. Using Pango directly will produce better results.
+ * 
+ * Return value: the newly loaded font, or %NULL if the font
+ * cannot be loaded.
+ */
 GdkFont *
 gdk_font_from_description_for_display (GdkDisplay           *display,
 				       PangoFontDescription *font_desc)
@@ -315,6 +340,18 @@ gdk_font_from_description (PangoFontDescription *font_desc)
   return gdk_font_from_description_for_display (gdk_get_default_display (),font_desc);
 }
 
+/**
+ * gdk_fontset_load_for_display:
+ * @display: a #GdkDisplay
+ * @fontset_name: a comma-separated list of XLFDs describing
+ *   the component fonts of the fontset to load.
+ * @returns: a #GdkFont, or %NULL if the fontset could not be loaded.
+ * 
+ * Loads a fontset for use on @display.
+ *
+ * The fontset may be newly loaded or looked up in a cache. 
+ * You should make no assumptions about the initial reference count.
+ */
 GdkFont *
 gdk_fontset_load_for_display (GdkDisplay  *display,
 			      const gchar *fontset_name)

gdk/x11/gdkkeys-x11.c

@@ -166,12 +166,11 @@ get_xkb (GdkKeymapX11 *keymap_x11)
  */
 
 /** 
- * gdk_keymap_get_for_display :
+ * gdk_keymap_get_for_display:
- * @display : the #GdkDisplay.
+ * @display: the #GdkDisplay.
+ * @returns: the #GdkKeymap attached to @display.
  *
- * Returns the GdkKeymap attached to @display.
+ * Returns the #GdkKeymap attached to @display.
- *
- * Returns : the GdkKeymap attached to @display.
  **/
 GdkKeymap*
 gdk_keymap_get_for_display (GdkDisplay *display)
@@ -188,6 +187,12 @@ gdk_keymap_get_for_display (GdkDisplay *display)
   return display_x11->keymap;
 }
 
+/** 
+ * gdk_keymap_get_default:
+ * @returns: the #GdkKeymap attached to the default display.
+ *
+ * Returns the #GdkKeymap attached to the default display.
+ **/
 GdkKeymap*
 gdk_keymap_get_default (void)
 {

gdk/x11/gdkscreen-x11.c

@@ -255,12 +255,28 @@ gdk_screen_x11_get_monitor_geometry (GdkScreen    *screen,
   *dest = screen_x11->monitors[num_monitor];
 }
 
+/**
+ * gdk_x11_screen_get_xscreen:
+ * @screen: a #GdkScreen.
+ * @returns: an Xlib <type>Screen*</type>
+ *
+ * Returns the screen of a #GdkScreen.
+ */
 Screen *
 gdk_x11_screen_get_xscreen (GdkScreen *screen)
 {
   return GDK_SCREEN_X11 (screen)->xscreen;
 }
 
+
+/**
+ * gdk_x11_screen_get_screen_number:
+ * @screen: a #GdkScreen.
+ * @returns: the position of @screen among the screens of
+ *   its display.
+ *
+ * Returns the index of a #GdkScreen.
+ */
 int
 gdk_x11_screen_get_screen_number (GdkScreen *screen)
 {