picture: Convert docs

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

1 files changed, 112 insertions, 100 deletions

diff --git a/gtk/gtkpicture.c b/gtk/gtkpicture.c
index 2317b93e55..768b10de96 100644
--- a/gtk/gtkpicture.c
+++ b/gtk/gtkpicture.c
@@ -38,6 +38,8 @@
  *
  * The `GtkPicture` widget displays a `GdkPaintable`.
  *
+ * ![An example GtkPicture](picture.png)
+ *
  * Many convenience functions are provided to make pictures simple to use.
  * For example, if you want to load an image from a file, and then display
  * it, there’s a convenience function to do this:
@@ -50,28 +52,28 @@
  * “broken image” icon similar to that used in many web browsers.
  * If you want to handle errors in loading the file yourself,
  * for example by displaying an error message, then load the image with
- * gdk_texture_new_from_file(), then create the #GtkPicture with
- * gtk_picture_new_for_paintable().
+ * [ctor@Gdk.Texture.new_from_file], then create the `GtkPicture` with
+ * [ctor@Gtk.Picture.new_for_paintable].
  *
  * Sometimes an application will want to avoid depending on external data
- * files, such as image files. See the documentation of #GResource for details.
- * In this case, gtk_picture_new_for_resource() and gtk_picture_set_resource()
- * should be used.
+ * files, such as image files. See the documentation of `GResource` for details.
+ * In this case, [ctor@Gtk.Picture.new_for_resource] and
+ * [method@Gtk.Picture.set_resource] should be used.
  *
- * GtkPicture displays an image at its natural size. See #GtkImage if you want
- * to display a fixed-size image, such as an icon.
+ * `GtkPicture` displays an image at its natural size. See [class@Gtk.Image]
+ * if you want to display a fixed-size image, such as an icon.
  *
  * ## Sizing the paintable
  *
- * You can influence how the paintable is displayed inside the #GtkPicture.
- * By turning off #GtkPicture:keep-aspect-ratio you can allow the paintable
- * to get stretched. #GtkPicture:can-shrink can be unset to make sure that
- * paintables are never made smaller than their ideal size - but be careful
- * if you do not know the size of the paintable in use (like when displaying
- * user-loaded images). This can easily cause the picture to grow larger than
- * the screen. And #GtkWidget:halign and #GtkWidget:valign can be used to make
- * sure the paintable doesn't fill all available space but is instead displayed
- * at its original size.
+ * You can influence how the paintable is displayed inside the `GtkPicture`.
+ * By turning off [property@Gtk.Picture:keep-aspect-ratio] you can allow the
+ * paintable to get stretched. [property@Gtk.Picture:can-shrink] can be unset
+ * to make sure that paintables are never made smaller than their ideal size -
+ * but be careful if you do not know the size of the paintable in use (like
+ * when displaying user-loaded images). This can easily cause the picture to
+ * grow larger than the screen. And [property@GtkWidget:halign] and
+ * [property@GtkWidget:valign] can be used to make sure the paintable doesn't
+ * fill all available space but is instead displayed at its original size.
  *
  * ## CSS nodes
  *
@@ -325,7 +327,7 @@ gtk_picture_class_init (GtkPictureClass *class)
   /**
    * GtkPicture:paintable:
    *
-   * The #GdkPaintable to be displayed by this #GtkPicture.
+   * The `GdkPaintable` to be displayed by this `GtkPicture`.
    */
   properties[PROP_PAINTABLE] =
       g_param_spec_object ("paintable",
@@ -337,7 +339,7 @@ gtk_picture_class_init (GtkPictureClass *class)
   /**
    * GtkPicture:file:
    *
-   * The #GFile that is displayed or %NULL if none.
+   * The `GFile` that is displayed or %NULL if none.
    */
   properties[PROP_FILE] =
       g_param_spec_object ("file",
@@ -362,7 +364,7 @@ gtk_picture_class_init (GtkPictureClass *class)
    * GtkPicture:keep-aspect-ratio:
    *
    * Whether the GtkPicture will render its contents trying to preserve the aspect
-   * ratio of the contents.
+   * ratio.
    */
   properties[PROP_KEEP_ASPECT_RATIO] =
       g_param_spec_boolean ("keep-aspect-ratio",
@@ -374,7 +376,7 @@ gtk_picture_class_init (GtkPictureClass *class)
   /**
    * GtkPicture:can-shrink
    *
-   * If the #GtkPicture can be made smaller than the self it contains.
+   * If the `GtkPicture` can be made smaller than the self it contains.
    */
   properties[PROP_CAN_SHRINK] =
       g_param_spec_boolean ("can-shrink",
@@ -399,10 +401,10 @@ gtk_picture_init (GtkPicture *self)
 /**
  * gtk_picture_new:
  *
- * Creates a new empty #GtkPicture widget.
+ * Creates a new empty `GtkPicture` widget.
  *
- * Returns: a newly created #GtkPicture widget.
- **/
+ * Returns: a newly created `GtkPicture` widget.
+ */
 GtkWidget*
 gtk_picture_new (void)
 {
@@ -411,15 +413,15 @@ gtk_picture_new (void)
 
 /**
  * gtk_picture_new_for_paintable:
- * @paintable: (nullable): a #GdkPaintable, or %NULL
+ * @paintable: (nullable): a `GdkPaintable`, or %NULL
  *
- * Creates a new #GtkPicture displaying @paintable.
+ * Creates a new `GtkPicture` displaying @paintable.
  *
- * The #GtkPicture will track changes to the @paintable and update
+ * The `GtkPicture` will track changes to the @paintable and update
  * its size and contents in response to it.
  *
- * Returns: a new #GtkPicture
- **/
+ * Returns: a new `GtkPicture`
+ */
 GtkWidget*
 gtk_picture_new_for_paintable (GdkPaintable *paintable)
 {
@@ -432,17 +434,17 @@ gtk_picture_new_for_paintable (GdkPaintable *paintable)
 
 /**
  * gtk_picture_new_for_pixbuf:
- * @pixbuf: (nullable): a #GdkPixbuf, or %NULL
+ * @pixbuf: (nullable): a `GdkPixbuf`, or %NULL
  *
- * Creates a new #GtkPicture displaying @pixbuf.
+ * Creates a new `GtkPicture` displaying @pixbuf.
  *
- * This is a utility function that calls gtk_picture_new_for_paintable(),
+ * This is a utility function that calls [ctor@Gtk.Picture.new_for_paintable],
  * See that function for details.
  *
  * The pixbuf must not be modified after passing it to this function.
  *
- * Returns: a new #GtkPicture
- **/
+ * Returns: a new `GtkPicture`
+ */
 GtkWidget*
 gtk_picture_new_for_pixbuf (GdkPixbuf *pixbuf)
 {
@@ -466,17 +468,19 @@ gtk_picture_new_for_pixbuf (GdkPixbuf *pixbuf)
 
 /**
  * gtk_picture_new_for_file:
- * @file: (nullable): a #GFile
- * 
- * Creates a new #GtkPicture displaying the given @file. If the file
- * isn’t found or can’t be loaded, the resulting #GtkPicture be empty.
+ * @file: (nullable): a `GFile`
+ *
+ * Creates a new `GtkPicture` displaying the given @file.
+ *
+ * If the file isn’t found or can’t be loaded, the resulting
+ * `GtkPicture` is empty.
  *
  * If you need to detect failures to load the file, use
- * gdk_texture_new_from_file() to load the file yourself, then create
- * the #GtkPicture from the texture.
+ * [ctor@Gdk.Texture.new_from_file] to load the file yourself,
+ * then create the `GtkPicture` from the texture.
  *
- * Returns: a new #GtkPicture
- **/
+ * Returns: a new `GtkPicture`
+ */
 GtkWidget*
 gtk_picture_new_for_file (GFile *file)
 {
@@ -491,13 +495,13 @@ gtk_picture_new_for_file (GFile *file)
  * gtk_picture_new_for_filename:
  * @filename: (type filename) (nullable): a filename
  *
- * Creates a new #GtkPicture displaying the file @filename.
+ * Creates a new `GtkPicture` displaying the file @filename.
  *
- * This is a utility function that calls gtk_picture_new_for_file().
+ * This is a utility function that calls [ctor@Gtk.Picture.new_for_file].
  * See that function for details.
  *
- * Returns: a new #GtkPicture
- **/
+ * Returns: a new `GtkPicture`
+ */
 GtkWidget*
 gtk_picture_new_for_filename (const char *filename)
 {
@@ -521,13 +525,13 @@ gtk_picture_new_for_filename (const char *filename)
  * gtk_picture_new_for_resource:
  * @resource_path: (nullable): resource path to play back
  *
- * Creates a new #GtkPicture displaying the resource at @resource_path.
+ * Creates a new `GtkPicture` displaying the resource at @resource_path.
  *
- * This is a utility function that calls gtk_picture_new_for_file().
+ * This is a utility function that calls [ctor@Gtk.Picture.new_for_file].
  * See that function for details.
  *
- * Returns: a new #GtkPicture
- **/
+ * Returns: a new `GtkPicture`
+ */
 GtkWidget *
 gtk_picture_new_for_resource (const char *resource_path)
 {
@@ -632,13 +636,13 @@ out1:
 
 /**
  * gtk_picture_set_file:
- * @self: a #GtkPicture
- * @file: (nullable): a %GFile or %NULL
+ * @self: a `GtkPicture`
+ * @file: (nullable): a `GFile` or %NULL
  *
  * Makes @self load and display @file.
  *
- * See gtk_picture_new_for_file() for details.
- **/
+ * See [ctor@Gtk.Picture.new_for_file] for details.
+ */
 void
 gtk_picture_set_file (GtkPicture *self,
                       GFile      *file)
@@ -665,14 +669,15 @@ gtk_picture_set_file (GtkPicture *self,
 
 /**
  * gtk_picture_get_file:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  *
- * Gets the #GFile currently displayed if @self is displaying a file.
- * If @self is not displaying a file, for example when gtk_picture_set_paintable()
- * was used, then %NULL is returned.
+ * Gets the `GFile` currently displayed if @self is displaying a file.
  *
- * Returns: (nullable) (transfer none): The #GFile displayed by @self.
- **/
+ * If @self is not displaying a file, for example when
+ * [method@Gtk.Picture.set_paintable] was used, then %NULL is returned.
+ *
+ * Returns: (nullable) (transfer none): The `GFile` displayed by @self.
+ */
 GFile *
 gtk_picture_get_file (GtkPicture *self)
 {
@@ -683,13 +688,13 @@ gtk_picture_get_file (GtkPicture *self)
 
 /**
  * gtk_picture_set_filename:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  * @filename: (nullable): the filename to play
  *
  * Makes @self load and display the given @filename.
  *
- * This is a utility function that calls gtk_picture_set_file().
- **/
+ * This is a utility function that calls [method@Gtk.Picture.set_file].
+ */
 void
 gtk_picture_set_filename (GtkPicture *self,
                           const char *filename)
@@ -711,14 +716,14 @@ gtk_picture_set_filename (GtkPicture *self,
 
 /**
  * gtk_picture_set_resource:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  * @resource_path: (nullable): the resource to set
  *
  * Makes @self load and display the resource at the given
  * @resource_path.
  *
- * This is a utility function that calls gtk_picture_set_file(),
- **/
+ * This is a utility function that calls [method@Gtk.Picture.set_file].
+ */
 void
 gtk_picture_set_resource (GtkPicture *self,
                           const char *resource_path)
@@ -752,13 +757,15 @@ gtk_picture_set_resource (GtkPicture *self,
 
 /**
  * gtk_picture_set_pixbuf:
- * @self: a #GtkPicture
- * @pixbuf: (nullable): a #GdkPixbuf or %NULL
+ * @self: a `GtkPicture`
+ * @pixbuf: (nullable): a `GdkPixbuf` or %NULL
+ *
+ * Sets a `GtkPicture` to show a `GdkPixbuf`.
  *
- * See gtk_picture_new_for_pixbuf() for details.
+ * See [ctor@Gtk.Picture.new_for_pixbuf] for details.
  *
- * This is a utility function that calls gtk_picture_set_paintable(),
- **/
+ * This is a utility function that calls [method@Gtk.Picture.set_paintable].
+ */
 void
 gtk_picture_set_pixbuf (GtkPicture *self,
                         GdkPixbuf  *pixbuf)
@@ -795,14 +802,15 @@ gtk_picture_paintable_invalidate_size (GdkPaintable *paintable,
 
 /**
  * gtk_picture_set_paintable:
- * @self: a #GtkPicture
- * @paintable: (nullable): a #GdkPaintable or %NULL
+ * @self: a `GtkPicture`
+ * @paintable: (nullable): a `GdkPaintable` or %NULL
+ *
+ * Makes @self display the given @paintable.
  *
- * Makes @self display the given @paintable. If @paintable is %NULL,
- * nothing will be displayed.
+ * If @paintable is %NULL, nothing will be displayed.
  *
- * See gtk_picture_new_for_paintable() for details.
- **/
+ * See [ctor@Gtk.Picture.new_for_paintable] for details.
+ */
 void
 gtk_picture_set_paintable (GtkPicture   *self,
                            GdkPaintable *paintable)
@@ -863,13 +871,13 @@ gtk_picture_set_paintable (GtkPicture   *self,
 
 /**
  * gtk_picture_get_paintable:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  *
- * Gets the #GdkPaintable being displayed by the #GtkPicture.
+ * Gets the `GdkPaintable` being displayed by the `GtkPicture`.
  *
  * Returns: (nullable) (transfer none): the displayed paintable, or %NULL if
  *   the picture is empty
- **/
+ */
 GdkPaintable *
 gtk_picture_get_paintable (GtkPicture *self)
 {
@@ -880,15 +888,17 @@ gtk_picture_get_paintable (GtkPicture *self)
 
 /**
  * gtk_picture_set_keep_aspect_ratio:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  * @keep_aspect_ratio: whether to keep aspect ratio
  *
  * If set to %TRUE, the @self will render its contents according to
- * their aspect ratio. That means that empty space may show up at the
- * top/bottom or left/right of @self.
+ * their aspect ratio.
+ *
+ * That means that empty space may show up at the top/bottom or
+ * left/right of @self.
  *
- * If set to %FALSE or if the contents provide no aspect ratio, the
- * contents will be stretched over the picture's whole area.
+ * If set to %FALSE or if the contents provide no aspect ratio,
+ * the contents will be stretched over the picture's whole area.
  */
 void
 gtk_picture_set_keep_aspect_ratio (GtkPicture *self,
@@ -905,12 +915,12 @@ gtk_picture_set_keep_aspect_ratio (GtkPicture *self,
 
 /**
  * gtk_picture_get_keep_aspect_ratio:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  *
- * Gets the value set via gtk_picture_set_keep_aspect_ratio().
+ * Returns whether the `GtkPicture` preserves its contents aspect ratio.
  *
  * Returns: %TRUE if the self tries to keep the contents' aspect ratio
- **/
+ */
 gboolean
 gtk_picture_get_keep_aspect_ratio (GtkPicture *self)
 {
@@ -921,18 +931,19 @@ gtk_picture_get_keep_aspect_ratio (GtkPicture *self)
 
 /**
  * gtk_picture_set_can_shrink:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  * @can_shrink: if @self can be made smaller than its contents
  *
  * If set to %TRUE, the @self can be made smaller than its contents.
+ *
  * The contents will then be scaled down when rendering.
  *
  * If you want to still force a minimum size manually, consider using
- * gtk_widget_set_size_request().
+ * [method@Gtk.Widget.set_size_request].
  *
  * Also of note is that a similar function for growing does not exist
  * because the grow behavior can be controlled via
- * gtk_widget_set_halign() and gtk_widget_set_valign().
+ * [method@Gtk.Widget.set_halign] and [method@Gtk.Widget.set_valign].
  */
 void
 gtk_picture_set_can_shrink (GtkPicture *self,
@@ -949,12 +960,12 @@ gtk_picture_set_can_shrink (GtkPicture *self,
 
 /**
  * gtk_picture_get_can_shrink:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  *
- * Gets the value set via gtk_picture_set_can_shrink().
+ * Returns whether the `GtkPicture` respects its contents size.
  *
  * Returns: %TRUE if the picture can be made smaller than its contents
- **/
+ */
 gboolean
 gtk_picture_get_can_shrink (GtkPicture *self)
 {
@@ -965,10 +976,11 @@ gtk_picture_get_can_shrink (GtkPicture *self)
 
 /**
  * gtk_picture_set_alternative_text:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
  * @alternative_text: (nullable): a textual description of the contents
  *
  * Sets an alternative textual description for the picture contents.
+ *
  * It is equivalent to the "alt" attribute for images on websites.
  *
  * This text will be made available to accessibility tools.
@@ -996,14 +1008,14 @@ gtk_picture_set_alternative_text (GtkPicture *self,
 
 /**
  * gtk_picture_get_alternative_text:
- * @self: a #GtkPicture
+ * @self: a `GtkPicture`
+ *
+ * Gets the alternative textual description of the picture.
  *
- * Gets the alternative textual description of the picture or returns %NULL if
- * the picture cannot be described textually.
+ * The returned string will be %NULL if the picture cannot be described textually.
  *
- * Returns: (nullable) (transfer none): the alternative textual description
- *     of @self.
- **/
+ * Returns: (nullable) (transfer none): the alternative textual description of @self.
+ */
 const char *
 gtk_picture_get_alternative_text (GtkPicture *self)
 {