Doc updates.

diff --git a/ChangeLog b/ChangeLog
index ec316cc394ff44ca08e9365c025f558c791783ca..3ee815c2319f66d3566ab8779cb63e12af977dfc 100644 (file)
--- a/ChangeLog
+++ b/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

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index ec316cc394ff44ca08e9365c025f558c791783ca..3ee815c2319f66d3566ab8779cb63e12af977dfc 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/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

diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2
index ec316cc394ff44ca08e9365c025f558c791783ca..3ee815c2319f66d3566ab8779cb63e12af977dfc 100644 (file)
--- a/ChangeLog.pre-2-2
+++ b/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

diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index ec316cc394ff44ca08e9365c025f558c791783ca..3ee815c2319f66d3566ab8779cb63e12af977dfc 100644 (file)
--- a/ChangeLog.pre-2-4
+++ b/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

diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index ec316cc394ff44ca08e9365c025f558c791783ca..3ee815c2319f66d3566ab8779cb63e12af977dfc 100644 (file)
--- a/ChangeLog.pre-2-6
+++ b/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

diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index ec316cc394ff44ca08e9365c025f558c791783ca..3ee815c2319f66d3566ab8779cb63e12af977dfc 100644 (file)
--- a/ChangeLog.pre-2-8
+++ b/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

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 734f9c7b36c6266beffa1d12ab26ec588783a422..17b88f436a68763f3bb525cf3a7e780cb4ffc162 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/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. 
 

diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt
index 1298b56583ea0c01fa4fb9c03e5d4d3b0b65a6e8..8c111d67bf9e89fdf7dc1b720d51ac165e89b063 100644 (file)
--- a/docs/reference/gdk/gdk-sections.txt
+++ b/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

diff --git a/docs/reference/gdk/tmpl/gdkdisplay.sgml b/docs/reference/gdk/tmpl/gdkdisplay.sgml
index 7962c663991e983d038410bf3595428ff277995c..65504c19342c43d29882ea33b1cad102120c51df 100644 (file)
--- a/docs/reference/gdk/tmpl/gdkdisplay.sgml
+++ b/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>

diff --git a/docs/reference/gdk/tmpl/gdkscreen.sgml b/docs/reference/gdk/tmpl/gdkscreen.sgml
index db18d3e0b5fbaa04352456d35fbc6d8e716c9ddd..d423d554e1fe367f683e95d736b897d3ff7351df 100644 (file)
--- a/docs/reference/gdk/tmpl/gdkscreen.sgml
+++ b/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 @window_at_pointer function in #GdkPointerHooks. It will be used
-when GDK gets multihead support. 
+The <structname>GdkScreen</structname> struct is the GDK representation of a
+ physical screen. All its fields are private and should not be accessed directly. 
 </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>
 

diff --git a/docs/reference/gdk/tmpl/x_interaction.sgml b/docs/reference/gdk/tmpl/x_interaction.sgml
index 4174cb4af4a37b9d413202cc269a8965a51d2a37..292f8518cc6d7ac765444f5e7b849b9a5752f810 100644 (file)
--- a/docs/reference/gdk/tmpl/x_interaction.sgml
+++ b/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: 

diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c
index 415ff27229554d467f1a82b53fd7bec9e7dfc842..078134d07fe66bc806dae953b89a89de238c8026 100644 (file)
--- a/gdk/gdkscreen.c
+++ b/gdk/gdkscreen.c
@@ -317,14 +317,13 @@ gdk_screen_get_monitor_at_point (GdkScreen *screen,
 }
 
 /**
- * gdk_screen_get_monitor_num_at_window:
- * @screen : a #GdkScreen.
- * @anid : a #GdkDrawable ID.
- *
- * Returns the monitor number in which the largest area of the bounding rectangle
- * of @anid resides. 
+ * gdk_screen_get_monitor_at_window:
+ * @screen: a #GdkScreen.
+ * @window: a #GdkWindow
+ * @returns: the monitor number in which most of @window is located.
  *
- * Returns: the monitor number in which most of @anid is located.
+ * Returns the number of the monitor in which the largest area of the bounding rectangle
+ * of @window resides. 
  **/
 gint 
 gdk_screen_get_monitor_at_window (GdkScreen      *screen,

diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c
index e700981805486dada1099f25180864aa76b89c4a..9f1425397b1556dce4d2c0ec68417f1c3e12a973 100644 (file)
--- a/gdk/x11/gdkdisplay-x11.c
+++ b/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;
 }
+
+

diff --git a/gdk/x11/gdkdnd-x11.c b/gdk/x11/gdkdnd-x11.c
index 7aa0bbf8718d4e96df272b5ea50aa51750970d17..a387bf520085ce814933b419e4e671da782bbcb1 100644 (file)
--- a/gdk/x11/gdkdnd-x11.c
+++ b/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,

diff --git a/gdk/x11/gdkfont-x11.c b/gdk/x11/gdkfont-x11.c
index 825934e8d95ee2c745ced765f4a774f3b648f26f..df962da1abc67d5229470a477a9163b0ba2f0ddf 100644 (file)
--- a/gdk/x11/gdkfont-x11.c
+++ b/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)

diff --git a/gdk/x11/gdkkeys-x11.c b/gdk/x11/gdkkeys-x11.c
index d0bf2794a053ba51b5de6a367c3f54fde039a9c2..7c0dc100b0b00fe0cfb6f9aa373a4b217edec254 100644 (file)
--- a/gdk/x11/gdkkeys-x11.c
+++ b/gdk/x11/gdkkeys-x11.c
@@ -166,12 +166,11 @@ get_xkb (GdkKeymapX11 *keymap_x11)
  */
 
 /** 
- * gdk_keymap_get_for_display :
- * @display : the #GdkDisplay.
+ * gdk_keymap_get_for_display:
+ * @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)
 {

diff --git a/gdk/x11/gdkscreen-x11.c b/gdk/x11/gdkscreen-x11.c
index 5113986a434ad721dc4316287d464bc3b4487120..559b2e347292ef7d003bcc835a616f34501da8a3 100644 (file)
--- a/gdk/x11/gdkscreen-x11.c
+++ b/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)
 {