docs: Move documentation to inline comments: gdkvisual

1 files changed, 32 insertions, 17 deletions

diff --git a/gdk/gdkvisual.h b/gdk/gdkvisual.h
index 714a0e666c..5fa4ad919c 100644
--- a/gdk/gdkvisual.h
+++ b/gdk/gdkvisual.h
@@ -79,29 +79,44 @@ typedef enum
   GDK_VISUAL_DIRECT_COLOR
 } GdkVisualType;
 
-/* The visual type.
- *   "type" is the type of visual this is (PseudoColor, TrueColor, etc).
- *   "depth" is the bit depth of this visual.
- *   "colormap_size" is the size of a colormap for this visual.
- *   "bits_per_rgb" is the number of significant bits per red, green and blue.
- *  The red, green and blue masks, shifts and precisions refer
- *   to value needed to calculate pixel values in TrueColor and DirectColor
- *   visuals. The "mask" is the significant bits within the pixel. The
- *   "shift" is the number of bits left we must shift a primary for it
- *   to be in position (according to the "mask"). "prec" refers to how
- *   much precision the pixel value contains for a particular primary.
+/**
+ * GdkVisual:
+ *
+ * The #GdkVisual structure contains information about
+ * a particular visual.
+ *
+ * <example id="rgbmask">
+ * <title>Constructing a pixel value from components</title>
+ * <programlisting>
+ * guint
+ * pixel_from_rgb (GdkVisual *visual,
+ *                 guchar r, guchar b, guchar g)
+ * {
+ *   return ((r >> (16 - visual->red_prec))   << visual->red_shift) |
+ *          ((g >> (16 - visual->green_prec)) << visual->green_shift) |
+ *          ((r >> (16 - visual->blue_prec))  << visual->blue_shift);
+ * }
+ * </programlisting>
+ * </example>
  */
 struct _GdkVisual
 {
+  /*< private >*/
   GObject parent_instance;
 
-  /*< private >*/
-  GdkVisualType GSEAL (type);
-  gint GSEAL (depth);
+  GdkVisualType GSEAL (type);      /* Type of visual this is (PseudoColor, TrueColor, etc) */
+  gint GSEAL (depth);              /* Bit depth of this visual */
   GdkByteOrder GSEAL (byte_order);
-  gint GSEAL (colormap_size);
-  gint GSEAL (bits_per_rgb);
-
+  gint GSEAL (colormap_size);      /* Size of a colormap for this visual */
+  gint GSEAL (bits_per_rgb);       /* Number of significant bits per red, green and blue. */
+
+  /* The red, green and blue masks, shifts and precisions refer
+   * to value needed to calculate pixel values in TrueColor and DirectColor
+   * visuals. The "mask" is the significant bits within the pixel. The
+   * "shift" is the number of bits left we must shift a primary for it
+   * to be in position (according to the "mask"). "prec" refers to how
+   * much precision the pixel value contains for a particular primary.
+   */
   guint32 GSEAL (red_mask);
   gint GSEAL (red_shift);
   gint GSEAL (red_prec);