passwordentry: Convert docs

Change link syntax, add an example image, generally clean things up.

gtk/gtkpasswordentry.c

@@ -39,21 +39,22 @@
 
 
 /**
- * SECTION:gtkpasswordentry
- * @Short_description: An entry for secrets
- * @Title: GtkPasswordEntry
+ * GtkPasswordEntry:
+ *
+ * `GtkPasswordEntry` is an entry that has been tailored for entering secrets.
+ *
+ * ![An example GtkPasswordEntry](password-entry.png)
  *
- * #GtkPasswordEntry is entry that has been tailored for entering secrets.
  * It does not show its contents in clear text, does not allow to copy it
  * to the clipboard, and it shows a warning when Caps Lock is engaged. If
- * the underlying platform allows it, GtkPasswordEntry will also place the
- * text in a non-pageable memory area, to avoid it being written out to
- * disk by the operating system.
+ * the underlying platform allows it, `GtkPasswordEntry` will also place
+ * the text in a non-pageable memory area, to avoid it being written out
+ * to disk by the operating system.
  *
  * Optionally, it can offer a way to reveal the contents in clear text.
  *
- * GtkPasswordEntry provides only minimal API and should be used with the
- * #GtkEditable API.
+ * `GtkPasswordEntry` provides only minimal API and should be used with
+ * the [iface@Gtk.Editable] API.
  *
  * # CSS Nodes
  *
@@ -64,14 +65,14 @@
  *     ┊
  * ]|
  *
- * GtkPasswordEntry has a single CSS node with name entry that carries
+ * `GtkPasswordEntry` has a single CSS node with name entry that carries
  * a .passwordstyle class. The text Css node below it has a child with
  * name image and style class .caps-lock-indicator for the Caps Lock
  * icon, and possibly other children.
  *
  * # Accessibility
  *
- * GtkPasswordEntry uses the #GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
+ * `GtkPasswordEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
  */
 
 struct _GtkPasswordEntry
@@ -431,6 +432,12 @@ gtk_password_entry_class_init (GtkPasswordEntryClass *klass)
   widget_class->grab_focus = gtk_widget_grab_focus_child;
   widget_class->focus = gtk_widget_focus_child;
 
+  /**
+   * GtkPasswordEntry:placeholder-text:
+   *
+   * The text that will be displayed in the `GtkPasswordEntry`
+   * when it is empty and unfocused.
+   */
   props[PROP_PLACEHOLDER_TEXT] =
       g_param_spec_string ("placeholder-text",
                            P_("Placeholder text"),
@@ -438,6 +445,11 @@ gtk_password_entry_class_init (GtkPasswordEntryClass *klass)
                            NULL,
                            GTK_PARAM_READWRITE);
 
+  /**
+   * GtkPasswordEntry:activates-default:
+   *
+   * Whether to activate the default widget when Enter is pressed.
+   */
   props[PROP_ACTIVATES_DEFAULT] =
       g_param_spec_boolean ("activates-default",
                             P_("Activates default"),
@@ -445,6 +457,11 @@ gtk_password_entry_class_init (GtkPasswordEntryClass *klass)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkPasswordEntry:show-peek-icon:
+   *
+   * Whether to show an icon for revealing the content.
+   */
   props[PROP_SHOW_PEEK_ICON] =
       g_param_spec_boolean ("show-peek-icon",
                             P_("Show Peek Icon"),
@@ -469,12 +486,12 @@ gtk_password_entry_class_init (GtkPasswordEntryClass *klass)
   gtk_editable_install_properties (object_class, NUM_PROPERTIES);
 
   /**
-   * GtkPasswordEntry:activate:
+   * GtkPasswordEntry::activate:
    * @self: The widget on which the signal is emitted
    *
-   * The ::activate signal is forwarded from the
-   * #GtkText::activated signal, which is a keybinding
-   * signal for all forms of the Enter key.
+   * Emitted when the entry is activated.
+   *
+   * The keybindings for this signal are all forms of the Enter key.
    */
   signals[ACTIVATE] =
     g_signal_new (I_("activate"),
@@ -547,9 +564,9 @@ gtk_password_entry_get_text_widget (GtkPasswordEntry *entry)
 /**
  * gtk_password_entry_new:
  *
- * Creates a #GtkPasswordEntry.
+ * Creates a `GtkPasswordEntry`.
  *
- * Returns: a new #GtkPasswordEntry
+ * Returns: a new `GtkPasswordEntry`
  */
 GtkWidget *
 gtk_password_entry_new (void)
@@ -559,11 +576,11 @@ gtk_password_entry_new (void)
 
 /**
  * gtk_password_entry_set_show_peek_icon:
- * @entry: a #GtkPasswordEntry
+ * @entry: a `GtkPasswordEntry`
  * @show_peek_icon: whether to show the peek icon
  *
  * Sets whether the entry should have a clickable icon
- * to show the contents of the entry in clear text.
+ * to reveal the contents.
  *
  * Setting this to %FALSE also hides the text again.
  */
@@ -612,10 +629,10 @@ gtk_password_entry_set_show_peek_icon (GtkPasswordEntry *entry,
 
 /**
  * gtk_password_entry_get_show_peek_icon:
- * @entry: a #GtkPasswordEntry
+ * @entry: a `GtkPasswordEntry`
  *
- * Returns whether the entry is showing a clickable icon
- * to reveal the contents of the entry in clear text.
+ * Returns whether the entry is showing an icon to
+ * reveal the contents.
  *
  * Returns: %TRUE if an icon is shown
  */
@@ -629,8 +646,8 @@ gtk_password_entry_get_show_peek_icon (GtkPasswordEntry *entry)
 
 /**
  * gtk_password_entry_set_extra_menu:
- * @entry: a #GtkPasswordEntry
- * @model: (allow-none): a #GMenuModel
+ * @entry: a `GtkPasswordEntry`
+ * @model: (allow-none): a `GMenuModel`
  *
  * Sets a menu model to add when constructing
  * the context menu for @entry.
@@ -675,7 +692,7 @@ gtk_password_entry_set_extra_menu (GtkPasswordEntry *entry,
 
 /**
  * gtk_password_entry_get_extra_menu:
- * @entry: a #GtkText
+ * @entry: a `GtkPasswordEntry`
  *
  * Gets the menu model set with gtk_password_entry_set_extra_menu().
  *