docs: Fix GtkListStore description

- Escape XML elements
- Remove old gtk-doc links
- Add a few internal links
- Use Markdown code blocks

gtk/gtkliststore.c

@@ -32,28 +32,29 @@
 /**
  * GtkListStore:
  *
- * A list-like data structure that can be used with the GtkTreeView
+ * A list-like data structure that can be used with the [class@Gtk.TreeView].
  *
  * The `GtkListStore` object is a list model for use with a `GtkTreeView`
  * widget.  It implements the `GtkTreeModel` interface, and consequentialy,
  * can use all of the methods available there.  It also implements the
  * `GtkTreeSortable` interface so it can be sorted by the view.
  * Finally, it also implements the tree
- * [drag and drop][gtk4-GtkTreeView-drag-and-drop]
+ * [drag](iface.TreeDragSource.html) and [drop](iface.TreeDragDest.html)
  * interfaces.
  *
- * The `GtkListStore` can accept most GObject types as a column type, though
+ * The `GtkListStore` can accept most `GType`s as a column type, though
  * it can’t accept all custom types.  Internally, it will keep a copy of
  * data passed in (such as a string or a boxed pointer).  Columns that
  * accept `GObject`s are handled a little differently.  The
  * `GtkListStore` will keep a reference to the object instead of copying the
  * value.  As a result, if the object is modified, it is up to the
- * application writer to call gtk_tree_model_row_changed() to emit the
- * `GtkTreeModel`::row_changed signal.  This most commonly affects lists with
- * `GdkTexture`s stored.
+ * application writer to call [method@Gtk.TreeModel.row_changed] to emit the
+ * [signal@Gtk.TreeModel::row_changed] signal. This most commonly affects lists
+ * with [class@Gdk.Texture]s stored.
  *
  * An example for creating a simple list store:
- * |[<!-- language="C" -->
+ *
+ * ```c
  * enum {
  *   COLUMN_STRING,
  *   COLUMN_INT,
@@ -101,14 +102,14 @@
  *                       COLUMN_BOOLEAN, TRUE,
  *                       -1);
  * }
- * ]|
+ * ```
  *
  * # Performance Considerations
  *
  * Internally, the `GtkListStore` was originally implemented with a linked list
  * with a tail pointer.  As a result, it was fast at data insertion and deletion,
  * and not fast at random data access.  The `GtkListStore` sets the
- * %GTK_TREE_MODEL_ITERS_PERSIST flag, which means that `GtkTreeIter`s can be
+ * `GTK_TREE_MODEL_ITERS_PERSIST` flag, which means that `GtkTreeIter`s can be
  * cached while the row exists.  Thus, if access to a particular row is needed
  * often and your code is expected to run on older versions of GTK, it is worth
  * keeping the iter around.
@@ -120,9 +121,9 @@
  * are atomic, in the sense that the row is being appended to the store and the
  * values filled in in a single operation with regard to `GtkTreeModel` signaling.
  * In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set()
- * will first create a row, which triggers the `GtkTreeModel`::row-inserted signal
+ * will first create a row, which triggers the `GtkTreeModel::row-inserted` signal
  * on `GtkListStore`. The row, however, is still empty, and any signal handler
- * connecting to `GtkTreeModel`::row-inserted on this particular store should be prepared
+ * connecting to `GtkTreeModel::row-inserted` on this particular store should be prepared
  * for the situation that the row might be empty. This is especially important
  * if you are wrapping the `GtkListStore` inside a `GtkTreeModel`Filter and are
  * using a `GtkTreeModel`FilterVisibleFunc. Using any of the non-atomic operations
@@ -132,15 +133,15 @@
  *
  * # GtkListStore as GtkBuildable
  *
- * The GtkListStore implementation of the GtkBuildable interface allows
- * to specify the model columns with a <columns> element that may contain
- * multiple <column> elements, each specifying one model column. The “type”
+ * The GtkListStore implementation of the [iface@Gtk.Buildable] interface allows
+ * to specify the model columns with a `<columns>` element that may contain
+ * multiple `<column>` elements, each specifying one model column. The “type”
  * attribute specifies the data type for the column.
  *
  * Additionally, it is possible to specify content for the list store
- * in the UI definition, with the <data> element. It can contain multiple
- * <row> elements, each specifying to content for one row of the list model.
- * Inside a <row>, the <col> elements specify the content for individual cells.
+ * in the UI definition, with the `<data>` element. It can contain multiple
+ * `<row>` elements, each specifying to content for one row of the list model.
+ * Inside a `<row>`, the `<col>` elements specify the content for individual cells.
  *
  * Note that it is probably more common to define your models in the code,
  * and one might consider it a layering violation to specify the content of
@@ -148,7 +149,8 @@
  * is to separate the two, as far as possible.
  *
  * An example of a UI Definition fragment for a list store:
- * |[<!-- language="C" -->
+ *
+ * ```xml
  * <object class="GtkListStore">
  *   <columns>
  *     <column type="gchararray"/>
@@ -168,7 +170,7 @@
  *     </row>
  *   </data>
  * </object>
- * ]|
+ * ```
  */