Docs: use // for comments in examples

Without sgml mode, we can't escape /* as /* anymore,
so just switch to // for comments in examples.

gdk/gdk.c

@@ -673,14 +673,14 @@ gdk_threads_dispatch_free (gpointer data)
  * static gboolean
  * idle_callback (gpointer data)
  * {
- *    /* gdk_threads_enter(); would be needed for g_idle_add() */
+ *    // gdk_threads_enter(); would be needed for g_idle_add()
  *
  *    SomeWidget *self = data;
- *    /* do stuff with self */
+ *    // do stuff with self
  *
  *    self->idle_id = 0;
  *
- *    /* gdk_threads_leave(); would be needed for g_idle_add() */
+ *    // gdk_threads_leave(); would be needed for g_idle_add()
  *    return FALSE;
  * }
  *
@@ -688,7 +688,7 @@ gdk_threads_dispatch_free (gpointer data)
  * some_widget_do_stuff_later (SomeWidget *self)
  * {
  *    self->idle_id = gdk_threads_add_idle (idle_callback, self)
- *    /* using g_idle_add() here would require thread protection in the callback */
+ *    // using g_idle_add() here would require thread protection in the callback
  * }
  *
  * static void
@@ -780,7 +780,7 @@ gdk_threads_add_idle (GSourceFunc    function,
  * {
  *    SomeWidget *self = data;
  *    
- *    /* do stuff with self */
+ *    // do stuff with self
  *    
  *    self->timeout_id = 0;
  *    

gdk/gdkdisplaymanager.c

@@ -91,14 +91,14 @@
  * #ifdef GDK_WINDOWING_X11
  *   if (GDK_IS_X11_DISPLAY (display))
  *     {
- *       /* make X11-specific calls here */
+ *       // make X11-specific calls here
  *     }
  *   else
  * #endif
  * #ifdef GDK_WINDOWING_QUARTZ
  *   if (GDK_IS_QUARTZ_DISPLAY (display))
  *     {
- *       /* make Quartz-specific calls here */
+ *       // make Quartz-specific calls here
 *     }
  *   else
  * #endif

gdk/gdkevents.c

@@ -1678,11 +1678,11 @@ gdk_event_get_source_device (const GdkEvent *event)
  *
  * |[<!-- language="C" -->
  * {
- *   /&ast; motion_event handler &ast;/
+ *   // motion_event handler
  *   x = motion_event->x;
  *   y = motion_event->y;
- *   /&ast; handle (x,y) motion &ast;/
- *   gdk_event_request_motions (motion_event); /&ast; handles is_hint events &ast;/
+ *   // handle (x,y) motion
+ *   gdk_event_request_motions (motion_event); // handles is_hint events
  * }
  * ]|
  *

gdk/gdkkeys.c

@@ -501,14 +501,14 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * `<Control>plus` accelerator `<Shift>` should be masked out.
  *
  * |[<!-- language="C" -->
- * /&ast; We want to ignore irrelevant modifiers like ScrollLock &ast;/;
+ * // We want to ignore irrelevant modifiers like ScrollLock
  * #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
  * gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
  *                                      event->state, event->group,
  *                                      &keyval, NULL, NULL, &consumed);
  * if (keyval == GDK_PLUS &&
  *     (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
- *   /&ast; Control was pressed &ast;/
+ *   // Control was pressed
  * ]|
  * 
  * An older interpretation @consumed_modifiers was that it contained
@@ -516,10 +516,10 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * this allowed accelerators to be stored with irrelevant consumed
  * modifiers, by doing:
  * |[<!-- language="C" -->
- * /&ast; XXX Don’t do this XXX &ast;/
+ * // XXX Don’t do this XXX
  * if (keyval == accel_keyval &&
  *     (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
- *   /&ast; Accelerator was pressed &ast;/
+ *   // Accelerator was pressed
  * ]|
  *
  * However, this did not work if multi-modifier combinations were

gdk/wayland/gdkdisplay-wayland.c

@@ -52,14 +52,14 @@
  * #ifdef GDK_WINDOWING_WAYLAND
  *   if (GDK_IS_WAYLAND_DISPLAY (display))
  *     {
- *       /* make Wayland-specific calls here */
+ *       // make Wayland-specific calls here
  *     }
  *   else
  * #endif
  * #ifdef GDK_WINDOWING_X11
  *   if (GDK_IS_X11_DISPLAY (display))
  *     {
- *       /* make X11-specific calls here */
+ *       // make X11-specific calls here
  *     }
  *   else
  * #endif

gdk/x11/gdkmain-x11.c

@@ -64,14 +64,14 @@
  * #ifdef GDK_WINDOWING_X11
  *   if (GDK_IS_X11_DISPLAY (display))
  *     {
- *       /* make X11-specific calls here */
+ *       // make X11-specific calls here
  *     }
  *   else
  * #endif
  * #ifdef GDK_WINDOWING_QUARTZ
  *   if (GDK_IS_QUARTZ_DISPLAY (display))
  *     {
- *       /* make Quartz-specific calls here &ast/
+ *       // make Quartz-specific calls here
  *     }
  *   else
  * #endif

gtk/deprecated/gtkradioaction.c

@@ -406,7 +406,7 @@ create_menu_item (GtkAction *action)
  *   GSList *group = NULL;
  *   GtkRadioAction *action;
  *  
- *   while (/* more actions to add */)
+ *   while ( ...more actions to add... /)
  *     {
  *        action = gtk_radio_action_new (...);
  *        
@@ -496,7 +496,7 @@ gtk_radio_action_set_group (GtkRadioAction *action,
  *   GtkRadioAction *action;
  *   GtkRadioAction *last_action;
  *  
- *   while (/* more actions to add */)
+ *   while ( ...more actions to add... /)
  *     {
  *        action = gtk_radio_action_new (...);
  *        

gtk/deprecated/gtkstock.c

@@ -496,7 +496,7 @@ static const GtkStockItem builtin_items [] =
  *   return (gchar*)g_dpgettext2 (GETTEXT_PACKAGE, msgctxt, msgid);
  * }
  *
- * /* ... */
+ * ...
  *
  * gtk_stock_add (items, G_N_ELEMENTS (items));
  * gtk_stock_set_translate_func ("odd-item-domain", my_translate_func, "odd items"); 

gtk/gtkaccellabel.c

@@ -72,21 +72,20 @@
  *   GtkWidget *save_item;
  *   GtkAccelGroup *accel_group;
  *
- *   /* Create a GtkAccelGroup and add it to the window. */
+ *   // Create a GtkAccelGroup and add it to the window.
  *   accel_group = gtk_accel_group_new ();
  *   gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
  *
- *   /* Create the menu item using the convenience function. */
+ *   // Create the menu item using the convenience function.
  *   save_item = gtk_menu_item_new_with_label ("Save");
  *   gtk_widget_show (save_item);
  *   gtk_container_add (GTK_CONTAINER (menu), save_item);
  *
- *   /* Now add the accelerator to the GtkMenuItem. Note that since we
- *    * called gtk_menu_item_new_with_label() to create the GtkMenuItem
- *    * the GtkAccelLabel is automatically set up to display the
- *    * GtkMenuItem accelerators. We just need to make sure we use
- *    * GTK_ACCEL_VISIBLE here.
- *    */
+ *   // Now add the accelerator to the GtkMenuItem. Note that since we
+ *   // called gtk_menu_item_new_with_label() to create the GtkMenuItem
+ *   // the GtkAccelLabel is automatically set up to display the
+ *   // GtkMenuItem accelerators. We just need to make sure we use
+ *   // GTK_ACCEL_VISIBLE here.
  *   gtk_widget_add_accelerator (save_item, "activate", accel_group,
  *                               GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
  * ]|

gtk/gtkcelllayout.c

@@ -104,9 +104,8 @@
  *   GtkCellRenderer *cell;
  *
  *   cell = gtk_cell_renderer_pixbuf_new ();
- *   /* The following call causes the default cell area for combo boxes,
- *    * a GtkCellAreaBox, to be instantiated
- *    */
+ *   // The following call causes the default cell area for combo boxes,
+ *   // a GtkCellAreaBox, to be instantiated
  *   gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE);
  *   ...
  * }
@@ -114,9 +113,7 @@
  * GtkWidget *
  * my_combo_box_new (GtkCellArea *area)
  * {
- *   /* This call is going to cause a warning
- *    * about area being ignored
- *    */
+ *   // This call is going to cause a warning about area being ignored
  *   return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL);
  * }
  * ]|

gtk/gtkcellrenderer.c

@@ -259,7 +259,7 @@ gtk_cell_renderer_class_init (GtkCellRendererClass *class)
    *     {
    *       GtkEntry *entry = GTK_ENTRY (editable);
    *       
-   *       /* ... create a GtkEntryCompletion */
+   *       // ... create a GtkEntryCompletion
    *       
    *       gtk_entry_set_completion (entry, completion);
    *     }

gtk/gtkcsscustomproperty.c

@@ -200,7 +200,7 @@ gtk_css_custom_property_create_initial_value (GParamSpec *pspec)
  * the engine property, either in a previous rule or within the same
  * one.
  * |[
- * * {
+ * * {
  *     engine: someengine;
  *     -SomeEngine-custom-property: 2;
  * }

gtk/gtkcssprovider.c

@@ -115,38 +115,47 @@
  *   the two selectors. E.g. `GtkNotebook > GtkLabel` matches
  *   GtkLabel widgets that are direct children of a GtkNotebook.
  *
- * An example of widget classes and names in selectors:
+ * ## Examples of widget classes and names in selectors
  *
+ * Theme labels that are descendants of a window:
  * |[
- * /* Theme labels that are descendants of a window */
  * GtkWindow GtkLabel {
  *     background-color: #898989
  * }
+ * ]|
  *
- * /* Theme notebooks, and anything that’s within these */
+ * Theme notebooks, and anything that’s within these:
+ * |[
  * GtkNotebook {
  *     background-color: #a939f0
  * }
+ * ]|
  *
- * /* Theme combo boxes, and entries that
- *  are direct children of a notebook */
+ * Theme combo boxes, and entries that are direct children of a notebook:
+ * |[
  * GtkComboBox,
  * GtkNotebook > GtkEntry {
  *     color: @fg_color;
  *     background-color: #1209a2
  * }
+ * ]|
  *
- * /* Theme any widget within a GtkBin */
+ * Theme any widget within a GtkBin:
+ * |[
  * GtkBin * {
  *     font: Sans 20
  * }
+ * ]|
  *
- * /* Theme a label named title-label */
+ * Theme a label named title-label:
+ * |[
  * GtkLabel#title-label {
  *     font: Sans 15
  * }
+ * ]|
  *
- * /* Theme any widget named main-entry */
+ * Theme any widget named main-entry:
+ * |[
  * #main-entry {
  *     background-color: #f0a810
  * }
@@ -166,14 +175,17 @@
  * a string as a widget class name if it contains any uppercase characters
  * (which should work for more widgets with names like GtkLabel).
  *
- * An example for style classes in selectors:
+ * ## Examples for style classes in selectors
+ *
+ * Theme all widgets defining the class entry:
  * |[
- * /* Theme all widgets defining the class entry */
  * .entry {
  *     color: #39f1f9;
  * }
+ * ]|
  *
- * /* Theme spinbuttons’ entry */
+ * Theme spinbuttons’ entry:
+ * |[
  * GtkSpinButton.entry {
  *     color: #900185
  * }
@@ -197,20 +209,25 @@
  * for a list of all regions
  * used by GTK+ widgets.
  *
- * An example for regions in selectors:
+ * ## Examples for regions in selectors
+ *
+ * Theme any label within a notebook:
  * |[
- * /* Theme any label within a notebook */
  * GtkNotebook GtkLabel {
  *     color: #f90192;
  * }
+ * ]|
  *
- * /* Theme labels within notebook tabs */
+ * Theme labels within notebook tabs:
+ * |[
  * GtkNotebook tab GtkLabel {
  *     color: #703910;
  * }
+ * ]|
  *
- * /* Theme labels in the any first notebook
- *  tab, both selectors are equivalent */
+ * Theme labels in the any first notebook tab, both selectors are
+ * equivalent:
+ * |[
  * GtkNotebook tab:nth-child(first) GtkLabel,
  * GtkNotebook tab:first-child GtkLabel {
  *     color: #89d012;
@@ -223,37 +240,47 @@
  * are :active, :prelight (or :hover), :insensitive, :selected, :focused
  * and :inconsistent.
  *
- * And example for styling specific widget states:
+ * ## Examples for styling specific widget states
+ *
+ * Theme active (pressed) buttons: 
  * |[
- * /* Theme active (pressed) buttons */
  * GtkButton:active {
  *     background-color: #0274d9;
  * }
+ * ]|
  *
- * /* Theme buttons with the mouse pointer on it,
- *    both are equivalent */
+ * Theme buttons with the mouse pointer on it, both are equivalent:
+ * |[
  * GtkButton:hover,
  * GtkButton:prelight {
  *     background-color: #3085a9;
  * }
+ * ]|
  *
- * /* Theme insensitive widgets, both are equivalent */
+ * Theme insensitive widgets, both are equivalent:
+ * |[
  * :insensitive,
  * *:insensitive {
  *     background-color: #320a91;
  * }
+ * ]|
  *
- * /* Theme selection colors in entries */
+ * Theme selection colors in entries:
+ * |[
  * GtkEntry:selected {
  *     background-color: #56f9a0;
  * }
+ * ]|
  *
- * /* Theme focused labels */
+ * Theme focused labels:
+ * |[
  * GtkLabel:focused {
  *     background-color: #b4940f;
  * }
+ * ]|
  *
- * /* Theme inconsistent checkbuttons */
+ * Theme inconsistent checkbuttons:
+ * |[
  * GtkCheckButton:inconsistent {
  *     background-color: #20395a;
  * }

gtk/gtkdialog.c

@@ -100,14 +100,14 @@
  *
  * An example for simple GtkDialog usage:
  * |[<!-- language="C" -->
- * /&ast; Function to open a dialog box with a message &ast;/
+ * // Function to open a dialog box with a message
  * void
  * quick_message (GtkWindow *parent, gchar *message)
  * {
  *  GtkWidget *dialog, *label, *content_area;
  *  GtkDialogFlags flags;
  *
- *  /&ast; Create the widgets &ast;/
+ *  // Create the widgets
  *  flags = GTK_DIALOG_DESTROY_WITH_PARENT;
  *  dialog = gtk_dialog_new_with_buttons ("Message",
  *                                        parent,
@@ -118,15 +118,14 @@
  *  content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
  *  label = gtk_label_new (message);
  *
- *  /&ast; Ensure that the dialog box is destroyed when the user
- *  responds &ast;/
+ *  // Ensure that the dialog box is destroyed when the user responds
  *
  *  g_signal_connect_swapped (dialog,
  *                            "response",
  *                            G_CALLBACK (gtk_widget_destroy),
  *                            dialog);
  *
- *  /&ast; Add the label, and show everything we’ve added &ast;/
+ *  // Add the label, and show everything we’ve added
  *
  *  gtk_container_add (GTK_CONTAINER (content_area), label);
  *  gtk_widget_show_all (dialog);

gtk/gtkdrawingarea.c

@@ -86,7 +86,7 @@
  *  return FALSE;
  * }
  * [...]
- *   GtkWidget *drawing_area = gtk_drawing_area_new ();
+ *   GtkWidget *drawing_area = gtk_drawing_area_new ();
  *   gtk_widget_set_size_request (drawing_area, 100, 100);
  *   g_signal_connect (G_OBJECT (drawing_area), "draw",
  *                     G_CALLBACK (draw_callback), NULL);

gtk/gtkexpander.c

@@ -60,11 +60,11 @@
  *
  *   if (gtk_expander_get_expanded (expander))
  *     {
- *       /* Show or create widgets */
+ *       // Show or create widgets
  *     }
  *   else
  *     {
- *       /* Hide or destroy widgets */
+ *       // Hide or destroy widgets
  *     }
  * }
  * ]|

gtk/gtkfilechooser.c

@@ -722,12 +722,12 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
  * |[<!-- language="C" -->
  * if (document_is_new)
  *   {
- *     /&ast; the user just created a new document &ast;/
+ *     // the user just created a new document
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
  *   {
- *     /&ast; the user edited an existing document &ast;/ 
+ *     // the user edited an existing document
  *     gtk_file_chooser_set_filename (chooser, existing_filename);
  *   }
  * ]|
@@ -1074,12 +1074,12 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
  * |[<!-- language="C" -->
  * if (document_is_new)
  *   {
- *     /&ast; the user just created a new document &ast;/
+ *     // the user just created a new document
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
  *   {
- *     /&ast; the user edited an existing document &ast;/ 
+ *     // the user edited an existing document
  *     gtk_file_chooser_set_uri (chooser, existing_uri);
  *   }
  * ]|
@@ -1440,13 +1440,13 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  * |[<!-- language="C" -->
  * if (document_is_new)
  *   {
- *     /&ast; the user just created a new document &ast;/
+ *     // the user just created a new document
  *     gtk_file_chooser_set_current_folder_file (chooser, default_file_for_saving);
  *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
  *   }
  * else
  *   {
- *     /&ast; the user edited an existing document &ast;/
+ *     // the user edited an existing document
  *     gtk_file_chooser_set_file (chooser, existing_file);
  *   }
  * ]|

gtk/gtkfilefilter.c

@@ -32,7 +32,7 @@
  * types; e.g. a filter for text/plain also matches a file with mime
  * type application/rtf, since application/rtf is a subclass of
  * text/plain. Note that #GtkFileFilter allows wildcards for the
- * subtype of a mime type, so you can e.g. filter for image/*.
+ * subtype of a mime type, so you can e.g. filter for image/\*.
  *
  * Normally, filters are used by adding them to a #GtkFileChooser,
  * see gtk_file_chooser_add_filter(), but it is also possible
@@ -52,7 +52,7 @@
  * <object class="GtkFileFilter">
  *   <mime-types>
  *     <mime-type>text/plain</mime-type>
- *     <mime-type>image/&ast;</mime-type>
+ *     <mime-type>image/ *</mime-type>
  *   </mime-types>
  *   <patterns>
  *     <pattern>*.txt</pattern>

gtk/gtkicontheme.c

@@ -120,9 +120,9 @@
  *
  * icon_theme = gtk_icon_theme_get_default ();
  * pixbuf = gtk_icon_theme_load_icon (icon_theme,
- *                                    "my-icon-name", /* icon name */
- *                                    48, /* icon size */
- *                                    0,  /* flags */
+ *                                    "my-icon-name", // icon name
+ *                                    48, // icon size
+ *                                    0,  // flags
  *                                    &error);
  * if (!pixbuf)
  *   {
@@ -131,7 +131,7 @@
  *   }
  * else
  *   {
- *     /* Use the pixbuf */
+ *     // Use the pixbuf
  *     g_object_unref (pixbuf);
  *   }
  * ]|

gtk/gtkimage.c

@@ -86,12 +86,9 @@
  *     g_print ("Event box clicked at coordinates %f,%f\n",
  *              event->x, event->y);
  *
- *     /* Returning TRUE means we handled the event,
- *      * so the signal emission should be stopped
- *      * (don’t call any further callbacks that
- *      * may be connected). Return FALSE to
- *      * continue invoking callbacks.
- *      */
+ *     // Returning TRUE means we handled the event, so the signal
+ *     // emission should be stopped (don’t call any further callbacks
+ *     // that may be connected). Return FALSE to continue invoking callbacks.
  *     return TRUE;
  *   }
  *

gtk/gtkinfobar.c

@@ -74,7 +74,7 @@
  *
  * A simple example for using a GtkInfoBar:
  * |[<!-- language="C" -->
- * /&ast; set up info bar &ast;/
+ * // set up info bar
  * GtkWidget *widget;
  * GtkInfoBar *bar;
  *
@@ -98,9 +98,9 @@
  *                  widget,
  *                  0, 2, 1, 1);
  *
- * /&ast; ... &ast;/
+ * ...
  *
- * /&ast; show an error message &ast;/
+ * // show an error message
  * gtk_label_set_text (GTK_LABEL (message_label), message);
  * gtk_info_bar_set_message_type (bar,
  *                                GTK_MESSAGE_ERROR);

gtk/gtklabel.c

@@ -107,7 +107,7 @@
  * the label is inside a button:
  *
  * |[<!-- language="C" -->
- *   /&ast; Pressing Alt+H will activate this button &ast;/
+ *   // Pressing Alt+H will activate this button
  *   button = gtk_button_new ();
  *   label = gtk_label_new_with_mnemonic ("_Hello");
  *   gtk_container_add (GTK_CONTAINER (button), label);
@@ -117,7 +117,7 @@
  * already inside:
  *
  * |[<!-- language="C" -->
- *   /&ast; Pressing Alt+H will activate this button &ast;/
+ *   // Pressing Alt+H will activate this button
  *   button = gtk_button_new_with_mnemonic ("_Hello");
  * ]|
  *
@@ -126,7 +126,7 @@
  * gtk_label_set_mnemonic_widget():
  *
  * |[<!-- language="C" -->
- *   /&ast; Pressing Alt+H will focus the entry &ast;/
+ *   // Pressing Alt+H will focus the entry
  *   entry = gtk_entry_new ();
  *   label = gtk_label_new_with_mnemonic ("_Hello");
  *   gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);

gtk/gtkliststore.c

@@ -79,7 +79,7 @@
  *
  *       some_data = get_some_data (i);
  *
- *       /* Add a new row to the model */
+ *       // Add a new row to the model
  *       gtk_list_store_append (list_store, &iter);
  *       gtk_list_store_set (list_store, &iter,
  *                           COLUMN_STRING, some_data,
@@ -87,13 +87,12 @@
  *                           COLUMN_BOOLEAN,  FALSE,
  *                           -1);
  *
- *       /* As the store will keep a copy of
- *        * the string internally, we free some_data.
- *        */
+ *       // As the store will keep a copy of the string internally,
+ *       // we free some_data.
  *       g_free (some_data);
  *     }
  *
- *   /* Modify a particular row */
+ *   // Modify a particular row
  *   path = gtk_tree_path_new_from_string ("4");
  *   gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
  *                            &iter,

gtk/gtkmain.c

@@ -59,27 +59,27 @@
  * int
  * main (int argc, char **argv)
  * {
- *   /* Initialize i18n support with
- *    bindtextdomain(), etc. */
+ *   // Initialize i18n support with bindtextdomain(), etc.
+ *
  *   ...
  *
- *   /* Initialize the widget set */
+ *   // Initialize the widget set
  *   gtk_init (&argc, &argv);
  *
- *   /* Create the main window */
+ *   // Create the main window
  *   mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  *
- *   /* Set up our GUI elements */
+ *   // Set up our GUI elements
+ *
  *   ...
  *
- *   /* Show the application window */
+ *   // Show the application window
  *   gtk_widget_show_all (mainwin);
  *
- *   /* Enter the main event loop, and
- *    wait for user interaction */
+ *   // Enter the main event loop, and wait for user interaction
  *   gtk_main ();
  *
- *   /* The user lost interest */
+ *   // The user lost interest
  *   return 0;
  * }
  * ]|
@@ -1251,12 +1251,12 @@ gtk_main_quit (void)
  * ## Updating the UI during a long computation
  *
  * |[<!-- language="C" -->
- *  /&ast; computation going on... &ast;/
+ *  // computation going on...
  *
  *  while (gtk_events_pending ())
  *    gtk_main_iteration ();
  *
- *  /&ast; ...computation continued &ast;/
+ *  // ...computation continued
  * ]|
  *
  * Returns: %TRUE if any events are pending, %FALSE otherwise

gtk/gtkmessagedialog.c

@@ -84,8 +84,8 @@
  *                                   filename,
  *                                   g_strerror (errno));
  *
- *  /* Destroy the dialog when the user responds to it
- *  (e.g. clicks a button) */
+ *  // Destroy the dialog when the user responds to it
+ *  // (e.g. clicks a button)
  *
  *  g_signal_connect_swapped (dialog, "response",
  *                            G_CALLBACK (gtk_widget_destroy),

gtk/gtkradiobutton.c

@@ -78,17 +78,17 @@
  *    box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 2);
  *    gtk_box_set_homogeneous (GTK_BOX (box), TRUE);
  *
- *    /* Create a radio button with a GtkEntry widget */
+ *    // Create a radio button with a GtkEntry widget
  *    radio1 = gtk_radio_button_new (NULL);
  *    entry = gtk_entry_new ();
  *    gtk_container_add (GTK_CONTAINER (radio1), entry);
  *
  *
- *    /* Create a radio button with a label */
+ *    // Create a radio button with a label
  *    radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radio1),
  *                                                          "I’m the second radio button.");
  *
- *    /* Pack them into a box, then show all the widgets */
+ *    // Pack them into a box, then show all the widgets
  *    gtk_box_pack_start (GTK_BOX (box), radio1, TRUE, TRUE, 2);
  *    gtk_box_pack_start (GTK_BOX (box), radio2, TRUE, TRUE, 2);
  *    gtk_container_add (GTK_CONTAINER (window), box);
@@ -358,7 +358,7 @@ gtk_radio_button_set_group (GtkRadioButton *radio_button,
  *   GtkRadioButton *radio_button;
  *   GtkRadioButton *last_button;
  *
- *   while (/* more buttons to add */)
+ *   while ( ...more buttons to add... )
  *     {
  *        radio_button = gtk_radio_button_new (...);
  *

gtk/gtkrecentfilter.c

@@ -32,7 +32,7 @@
  * types; e.g. a filter for text/plain also matches a file with mime
  * type application/rtf, since application/rtf is a subclass of text/plain.
  * Note that #GtkRecentFilter allows wildcards for the subtype of a
- * mime type, so you can e.g. filter for image/*.
+ * mime type, so you can e.g. filter for image/\*.
  *
  * Normally, filters are used by adding them to a #GtkRecentChooser,
  * see gtk_recent_chooser_add_filter(), but it is also possible to

gtk/gtkrecentmanager.c

@@ -67,7 +67,7 @@
  *   }
  * else
  *  {
- *    /* Use the info object */
+ *    // Use the info object
  *    gtk_recent_info_unref (info);
  *  }
  * ]|

gtk/gtksettings.c

@@ -89,7 +89,7 @@
  * |[<!-- language="C" -->
  *   gtk_init (&argc, &argv);
  *
- *   /&ast; make sure the type is realized &ast;/
+ *   // make sure the type is realized
  *   g_type_class_unref (g_type_class_ref (GTK_TYPE_IMAGE_MENU_ITEM));
  *
  *   g_object_set (gtk_settings_get_default (), "gtk-enable-animations", FALSE, NULL);

gtk/gtksocket.c

@@ -75,9 +75,8 @@
  * gtk_widget_show (socket);
  * gtk_container_add (GTK_CONTAINER (parent), socket);
  *
- * /* The following call is only necessary if one of
- *  * the ancestors of the socket is not yet visible.
- *  */
+ * // The following call is only necessary if one of
+ * // the ancestors of the socket is not yet visible.
  * gtk_widget_realize (socket);
  * g_print ("The ID of the sockets window is %#x\n",
  *          gtk_socket_get_id (socket));

gtk/gtkspinbutton.c

@@ -81,10 +81,8 @@
  * ## Using a GtkSpinButton to get an integer
  *
  * |[<!-- language="C" -->
- * /&ast; Provides a function to retrieve an integer value from a
- *  &ast; GtkSpinButton and creates a spin button to model percentage
- *  &ast; values.
- *  &ast;/
+ * // Provides a function to retrieve an integer value from a GtkSpinButton
+ * // and creates a spin button to model percentage values.
  *
  * gint
  * grab_int_value (GtkSpinButton *button,
@@ -105,7 +103,7 @@
  *   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  *   gtk_container_set_border_width (GTK_CONTAINER (window), 5);
  *
- *   /&ast; creates the spinbutton, with no decimal places &ast;/
+ *   // creates the spinbutton, with no decimal places
  *   button = gtk_spin_button_new (adjustment, 1.0, 0);
  *   gtk_container_add (GTK_CONTAINER (window), button);
  *
@@ -116,9 +114,8 @@
  * ## Using a GtkSpinButton to get a floating point value
  *
  * |[<!-- language="C" -->
- * /&ast; Provides a function to retrieve a floating point value from a
- *  &ast; GtkSpinButton, and creates a high precision spin button.
- *  &ast;/
+ * // Provides a function to retrieve a floating point value from a
+ * // GtkSpinButton, and creates a high precision spin button.
  *
  * gfloat
  * grab_float_value (GtkSpinButton *button,
@@ -138,7 +135,7 @@
  *   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  *   gtk_container_set_border_width (GTK_CONTAINER (window), 5);
  *
- *   /&ast; creates the spinbutton, with three decimal places &ast;/
+ *   // creates the spinbutton, with three decimal places
  *   button = gtk_spin_button_new (adjustment, 0.001, 3);
  *   gtk_container_add (GTK_CONTAINER (window), button);
  *
@@ -457,7 +454,7 @@ gtk_spin_button_class_init (GtkSpinButtonClass *class)
    * The ::output signal can be used to change to formatting
    * of the value that is displayed in the spin buttons entry.
    * |[<!-- language="C" -->
-   * /&ast; show leading zeros &ast;/
+   * // show leading zeros
    * static gboolean
    * on_output (GtkSpinButton *spin,
    *            gpointer       data)

gtk/gtktextview.c

@@ -7395,7 +7395,7 @@ gtk_text_view_reset_im_context (GtkTextView *text_view)
  *         return TRUE;
  *     }
  *
- *     /* Do some stuff */
+ *     // Do some stuff
  *
  *   return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class)->key_press_event (widget, event);
  * }

gtk/gtktogglebutton.c

@@ -72,7 +72,7 @@
  *    text = "Hi, i’m a toggle button.";
  *    toggle1 = gtk_toggle_button_new_with_label (text);
  *
- *    /* Makes this toggle button invisible */
+ *    // Makes this toggle button invisible
  *    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1),
  *                                TRUE);
  *

gtk/gtktoolpalette.c

@@ -86,14 +86,14 @@
  *   GtkWidget *palette;
  *   GtkWidget *item;
  *
- *   /* Get the dragged item */
+ *   // Get the dragged item
  *   palette = gtk_widget_get_ancestor (gtk_drag_get_source_widget (context),
  *                                      GTK_TYPE_TOOL_PALETTE);
  *   if (palette != NULL)
  *     item = gtk_tool_palette_get_drag_item (GTK_TOOL_PALETTE (palette),
  *                                            selection);
  *
- *   /* Do something with item */
+ *   // Do something with item
  * }
  *
  * GtkWidget *target, palette;

gtk/gtktreemodel.c

@@ -116,23 +116,22 @@
  * ## Acquiring a #GtkTreeIter-struct
  *
  * |[<!-- language="C" -->
- *  /&ast; Three ways of getting the iter pointing to the
- *   location &ast;/
+ * // Three ways of getting the iter pointing to the location
  * GtkTreePath *path;
  * GtkTreeIter iter;
  * GtkTreeIter parent_iter;
  *
- * /&ast; get the iterator from a string &ast;/
+ * // get the iterator from a string
  * gtk_tree_model_get_iter_from_string (model,
  *                                      &iter,
  *                                      "3:2:5");
  *
- * /&ast; get the iterator from a path &ast;/
+ * // get the iterator from a path
  * path = gtk_tree_path_new_from_string ("3:2:5");
  * gtk_tree_model_get_iter (model, &iter, path);
  * gtk_tree_path_free (path);
  *
- * /&ast; walk the tree to find the iterator &ast;/
+ * // walk the tree to find the iterator
  * gtk_tree_model_iter_nth_child (model, &iter,
  *                                NULL, 3);
  * parent_iter = iter;
@@ -166,17 +165,16 @@
  * gboolean valid;
  * gint row_count = 0;
  *
- * /&ast; make a new list_store &ast;/
+ * // make a new list_store
  * list_store = gtk_list_store_new (N_COLUMNS,
  *                                  G_TYPE_STRING,
  *                                  G_TYPE_INT);
  *
- * /&ast; Fill the list store with data &ast;/
+ * // Fill the list store with data
  * populate_model (list_store);
  *
- * /&ast; Get the first iter in the list, check it is
- *  valid and walk through the list, reading each row.
- * &ast;/
+ * // Get the first iter in the list, check it is valid and walk
+ * // through the list, reading each row.
  *
  * valid = gtk_tree_model_get_iter_first (list_store,
  *                                        &iter);
@@ -185,15 +183,13 @@
  *    gchar *str_data;
  *    gint   int_data;
  *
- *    /&ast; Make sure you terminate calls to
- *     &ast; gtk_tree_model_get() with a “-1” value
- *     &ast;/
+ *    // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value
  *    gtk_tree_model_get (list_store, &iter,
  *                        STRING_COLUMN, &str_data,
  *                        INT_COLUMN, &int_data,
  *                        -1);
  *
- *    /&ast; Do something with the data &ast;/
+ *    // Do something with the data
  *    g_print ("Row %d: (%s,%d)\n",
  *             row_count, str_data, int_data);
  *    g_free (str_data);

gtk/gtktreemodelfilter.c

@@ -3830,7 +3830,7 @@ gtk_tree_model_filter_get_model (GtkTreeModelFilter *filter)
  *               GtkTreeIter  *iter,
  *               gpointer      data)
  * {
- *   /* Visible if row is non-empty and first column is “HI” */
+ *   // Visible if row is non-empty and first column is “HI”
  *   gchar *str;
  *   gboolean visible = FALSE;
  *

gtk/gtktreemodelsort.c

@@ -60,18 +60,18 @@
  *   GtkTreeModel *sort_model2;
  *   GtkTreeModel *child_model;
  *
- *   /* get the child model */
+ *   // get the child model
  *   child_model = get_my_model ();
  *
- *   /* Create the first tree */
+ *   // Create the first tree
  *   sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
  *   tree_view1 = gtk_tree_view_new_with_model (sort_model1);
  *
- *   /* Create the second tree */
+ *   // Create the second tree
  *   sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
  *   tree_view2 = gtk_tree_view_new_with_model (sort_model2);
  *
- *   /* Now we can sort the two models independently */
+ *   // Now we can sort the two models independently
  *   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
  *                                         COLUMN_1, GTK_SORT_ASCENDING);
  *   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
@@ -98,15 +98,14 @@
  *   char *some_data = NULL;
  *   char *modified_data;
  *
- *   /* Get the current selected row and the model. */
+ *   // Get the current selected row and the model.
  *   if (! gtk_tree_selection_get_selected (selection,
  *                                          &sort_model,
  *                                          &sort_iter))
  *     return;
  *
- *   /* Look up the current value on the selected row and get
- *    * a new value to change it to.
- *    */
+ *   // Look up the current value on the selected row and get
+ *   // a new value to change it to.
  *   gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
  *                       COLUMN_1, &some_data,
  *                       -1);
@@ -114,15 +113,14 @@
  *   modified_data = change_the_data (some_data);
  *   g_free (some_data);
  *
- *   /* Get an iterator on the child model, instead of the sort model. */
+ *   // Get an iterator on the child model, instead of the sort model.
  *   gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
  *                                                   &child_iter,
  *                                                   &sort_iter);
  *
- *   /* Get the child model and change the value of the row. In this
- *    * example, the child model is a GtkListStore. It could be any other
- *    * type of model, though.
- *    */
+ *   // Get the child model and change the value of the row. In this
+ *   // example, the child model is a GtkListStore. It could be any other
+ *   // type of model, though.
  *   child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
  *   gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
  *                       COLUMN_1, &modified_data,

gtk/gtkwidget.c

@@ -2988,10 +2988,10 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    *    {
    *      private_data->suggested_action = 0;
    *
-   *      /* We are getting this data due to a request in
-   *      drag_motion, rather than due to a request in drag_drop,
-   *      so we are just supposed to call gdk_drag_status(), not
-   *      actually paste in the data. */
+   *      // We are getting this data due to a request in drag_motion,
+   *      // rather than due to a request in drag_drop, so we are just
+   *      // supposed to call gdk_drag_status(), not actually paste in
+   *      // the data.
    *
    *      str = gtk_selection_data_get_text (selection_data);
    *      if (!data_is_acceptable (str))
@@ -3003,7 +3003,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    *    }
    *   else
    *    {
-   *      /* accept the drop */
+   *      // accept the drop
    *    }
    * }
    * ]|
@@ -3127,7 +3127,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    *     {
    *       GdkDragAction action;
    *
-   *       /* handle data here */
+   *       // handle data here
    *
    *       action = gdk_drag_context_get_selected_action (context);
    *       if (action == GDK_ACTION_ASK)
@@ -10782,7 +10782,7 @@ gtk_widget_add_device_events (GtkWidget    *widget,
  *  GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
  *  if (gtk_widget_is_toplevel (toplevel))
  *    {
- *      /* Perform action on toplevel. */
+ *      // Perform action on toplevel.
  *    }
  * ]|
  *

gtk/gtkwindow.c

@@ -11394,7 +11394,7 @@ gtk_XParseGeometry (const char   *string,
  * static void
  * fill_with_content (GtkWidget *vbox)
  * {
- *   /* fill with content... */
+ *   // fill with content...
  * }
  *
  * int