[gtk/ebassi/gidocgen: 150/465] bitset: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 150/465] bitset: Convert docs
- Date: Mon, 8 Mar 2021 22:26:08 +0000 (UTC)
commit 1fd0e8f277205fe9d1c30a2d693e4512d7a0c32c
Author: Matthias Clasen <mclasen redhat com>
Date: Thu Feb 25 07:01:11 2021 -0500
bitset: Convert docs
gtk/gtkbitset.c | 259 +++++++++++++++++++++++++++++---------------------------
gtk/gtkbitset.h | 9 +-
2 files changed, 139 insertions(+), 129 deletions(-)
---
diff --git a/gtk/gtkbitset.c b/gtk/gtkbitset.c
index 05953391b7..af55601187 100644
--- a/gtk/gtkbitset.c
+++ b/gtk/gtkbitset.c
@@ -24,32 +24,25 @@
#include "roaring/roaring.c"
/**
- * SECTION:gtkbitset
- * @title: GtkBitset
- * @short_description: Sets of integers
- * @see_also: #GtkSelectionModel
+ * GtkBitset: (ref-func gtk_bitset_ref) (unref-func gtk_bitset_unref)
+ *
+ * A `GtkBitset` represents a set of unsigned integers.
*
- * #GtkBitset is a data structure for representing a set of unsigned integers.
* Another name for this data structure is "bitmap".
*
* The current implementation is based on [roaring bitmaps](https://roaringbitmap.org/).
*
* A bitset allows adding a set of integers and provides support for set operations
* like unions, intersections and checks for equality or if a value is contained
- * in the set. #GtkBitset also contains various functions to query metadata about
+ * in the set. `GtkBitset` also contains various functions to query metadata about
* the bitset, such as the minimum or maximum values or its size.
*
- * The fastest way to iterate values in a bitset is #GtkBitsetIter.
+ * The fastest way to iterate values in a bitset is [struct@Gtk.BitsetIter].
*
- * The main use case for #GtkBitset is implementing complex selections for
- * #GtkSelectionModel.
+ * The main use case for `GtkBitset` is implementing complex selections for
+ * [iface@Gtk.SelectionModel].
*/
-/**
- * GtkBitset: (ref-func gtk_bitset_ref) (unref-func gtk_bitset_unref)
- *
- * The `GtkBitset` structure contains only private data.
- */
struct _GtkBitset
{
int ref_count;
@@ -63,11 +56,11 @@ G_DEFINE_BOXED_TYPE (GtkBitset, gtk_bitset,
/**
* gtk_bitset_ref:
- * @self: (allow-none): a #GtkBitset
+ * @self: (allow-none): a `GtkBitset`
*
- * Acquires a reference on the given #GtkBitset.
+ * Acquires a reference on the given `GtkBitset`.
*
- * Returns: (transfer none): the #GtkBitset with an additional reference
+ * Returns: (transfer none): the `GtkBitset` with an additional reference
*/
GtkBitset *
gtk_bitset_ref (GtkBitset *self)
@@ -81,9 +74,9 @@ gtk_bitset_ref (GtkBitset *self)
/**
* gtk_bitset_unref:
- * @self: (allow-none): a #GtkBitset
+ * @self: (allow-none): a `GtkBitset`
*
- * Releases a reference on the given #GtkBitset.
+ * Releases a reference on the given `GtkBitset`.
*
* If the reference was the last, the resources associated to the @self are
* freed.
@@ -104,7 +97,7 @@ gtk_bitset_unref (GtkBitset *self)
/**
* gtk_bitset_contains:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @value: the value to check
*
* Checks if the given @value has been added to @self
@@ -122,7 +115,7 @@ gtk_bitset_contains (const GtkBitset *self,
/**
* gtk_bitset_is_empty:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
*
* Check if no value is contained in bitset.
*
@@ -138,8 +131,8 @@ gtk_bitset_is_empty (const GtkBitset *self)
/**
* gtk_bitset_equals:
- * @self: a #GtkBitset
- * @other: another #GtkBitset
+ * @self: a `GtkBitset`
+ * @other: another `GtkBitset`
*
* Returns %TRUE if @self and @other contain the same values.
*
@@ -160,10 +153,11 @@ gtk_bitset_equals (const GtkBitset *self,
/**
* gtk_bitset_get_minimum:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
+ *
+ * Returns the smallest value in @self.
*
- * Returns the smallest value in @self. If @self is empty,
- * G_MAXUINT is returned.
+ * If @self is empty, `G_MAXUINT` is returned.
*
* Returns: The smallest value in @self
**/
@@ -177,10 +171,11 @@ gtk_bitset_get_minimum (const GtkBitset *self)
/**
* gtk_bitset_get_maximum:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
+ *
+ * Returns the largest value in @self.
*
- * Returns the largest value in @self. If @self is empty,
- * 0 is returned.
+ * If @self is empty, 0 is returned.
*
* Returns: The largest value in @self
**/
@@ -194,17 +189,19 @@ gtk_bitset_get_maximum (const GtkBitset *self)
/**
* gtk_bitset_get_size:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
*
* Gets the number of values that were added to the set.
+ *
* For example, if the set is empty, 0 is returned.
*
- * Note that this function returns a #guint64, because when all values are
- * set, the return value is #G_MAXUINT + 1. Unless you are sure this cannot
- * happen (it can't with #GListModel), be sure to use a 64bit type.
+ * Note that this function returns a `guint64`, because when all
+ * values are set, the return value is `G_MAXUINT + 1`. Unless you
+ * are sure this cannot happen (it can't with `GListModel`), be sure
+ * to use a 64bit type.
*
* Returns: The number of values in the set.
- **/
+ */
guint64
gtk_bitset_get_size (const GtkBitset *self)
{
@@ -215,19 +212,19 @@ gtk_bitset_get_size (const GtkBitset *self)
/**
* gtk_bitset_get_size_in_range:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @first: the first element to include
* @last: the last element to include
*
* Gets the number of values that are part of the set from @first to @last
* (inclusive).
*
- * Note that this function returns a #guint64, because when all values are
- * set, the return value is #G_MAXUINT + 1. Unless you are sure this cannot
- * happen (it can't with #GListModel), be sure to use a 64bit type.
+ * Note that this function returns a `guint64`, because when all values are
+ * set, the return value is `G_MAXUINT + 1`. Unless you are sure this cannot
+ * happen (it can't with `GListModel`), be sure to use a 64bit type.
*
* Returns: The number of values in the set from @first to @last.
- **/
+ */
guint64
gtk_bitset_get_size_in_range (const GtkBitset *self,
guint first,
@@ -241,7 +238,7 @@ gtk_bitset_get_size_in_range (const GtkBitset *self,
/**
* gtk_bitset_get_nth:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @nth: index of the item to get
*
* Returns the value of the @nth item in self.
@@ -249,7 +246,7 @@ gtk_bitset_get_size_in_range (const GtkBitset *self,
* If @nth is >= the size of @self, 0 is returned.
*
* Returns: the value of the @nth item in @self
- **/
+ */
guint
gtk_bitset_get_nth (const GtkBitset *self,
guint nth)
@@ -268,7 +265,7 @@ gtk_bitset_get_nth (const GtkBitset *self,
* Creates a new empty bitset.
*
* Returns: A new empty bitset
- **/
+ */
GtkBitset *
gtk_bitset_new_empty (void)
{
@@ -307,13 +304,13 @@ gtk_bitset_new_range (guint start,
/**
* gtk_bitset_copy:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
*
* Creates a copy of @self.
*
* Returns: (transfer full): A new bitset that contains the same
* values as @self
- **/
+ */
GtkBitset *
gtk_bitset_copy (const GtkBitset *self)
{
@@ -329,10 +326,10 @@ gtk_bitset_copy (const GtkBitset *self)
/**
* gtk_bitset_remove_all:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
*
* Removes all values from the bitset so that it is empty again.
- **/
+ */
void
gtk_bitset_remove_all (GtkBitset *self)
{
@@ -343,14 +340,14 @@ gtk_bitset_remove_all (GtkBitset *self)
/**
* gtk_bitset_add:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @value: value to add
*
* Adds @value to @self if it wasn't part of it before.
*
* Returns: %TRUE if @value was not part of @self and @self
* was changed.
- **/
+ */
gboolean
gtk_bitset_add (GtkBitset *self,
guint value)
@@ -362,14 +359,14 @@ gtk_bitset_add (GtkBitset *self,
/**
* gtk_bitset_remove:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @value: value to add
*
* Removes @value from @self if it was part of it before.
*
* Returns: %TRUE if @value was part of @self and @self
* was changed.
- **/
+ */
gboolean
gtk_bitset_remove (GtkBitset *self,
guint value)
@@ -381,13 +378,13 @@ gtk_bitset_remove (GtkBitset *self,
/**
* gtk_bitset_add_range:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @start: first value to add
* @n_items: number of consecutive values to add
*
* Adds all values from @start (inclusive) to @start + @n_items
* (exclusive) in @self.
- **/
+ */
void
gtk_bitset_add_range (GtkBitset *self,
guint start,
@@ -406,13 +403,13 @@ gtk_bitset_add_range (GtkBitset *self,
/**
* gtk_bitset_remove_range:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @start: first value to remove
* @n_items: number of consecutive values to remove
*
* Removes all values from @start (inclusive) to @start + @n_items (exclusive)
* in @self.
- **/
+ */
void
gtk_bitset_remove_range (GtkBitset *self,
guint start,
@@ -431,13 +428,13 @@ gtk_bitset_remove_range (GtkBitset *self,
/**
* gtk_bitset_add_range_closed:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @first: first value to add
* @last: last value to add
*
* Adds the closed range [@first, @last], so @first, @last and all
* values in between. @first must be smaller than @last.
- **/
+ */
void
gtk_bitset_add_range_closed (GtkBitset *self,
guint first,
@@ -451,13 +448,13 @@ gtk_bitset_add_range_closed (GtkBitset *self,
/**
* gtk_bitset_remove_range_closed:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @first: first value to remove
* @last: last value to remove
*
* Removes the closed range [@first, @last], so @first, @last and all
* values in between. @first must be smaller than @last.
- **/
+ */
void
gtk_bitset_remove_range_closed (GtkBitset *self,
guint first,
@@ -471,7 +468,7 @@ gtk_bitset_remove_range_closed (GtkBitset *self,
/**
* gtk_bitset_add_rectangle:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @start: first value to add
* @width: width of the rectangle
* @height: height of the rectangle
@@ -479,7 +476,7 @@ gtk_bitset_remove_range_closed (GtkBitset *self,
*
* Interprets the values as a 2-dimensional boolean grid with the given @stride
* and inside that grid, adds a rectangle with the given @width and @height.
- **/
+ */
void
gtk_bitset_add_rectangle (GtkBitset *self,
guint start,
@@ -502,7 +499,7 @@ gtk_bitset_add_rectangle (GtkBitset *self,
/**
* gtk_bitset_remove_rectangle:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @start: first value to remove
* @width: width of the rectangle
* @height: height of the rectangle
@@ -510,7 +507,7 @@ gtk_bitset_add_rectangle (GtkBitset *self,
*
* Interprets the values as a 2-dimensional boolean grid with the given @stride
* and inside that grid, removes a rectangle with the given @width and @height.
- **/
+ */
void
gtk_bitset_remove_rectangle (GtkBitset *self,
guint start,
@@ -533,15 +530,16 @@ gtk_bitset_remove_rectangle (GtkBitset *self,
/**
* gtk_bitset_union:
- * @self: a #GtkBitset
- * @other: the #GtkBitset to union with
+ * @self: a `GtkBitset`
+ * @other: the `GtkBitset` to union with
*
- * Sets @self to be the union of @self and @other, that is add all values
- * from @other into @self that weren't part of it.
+ * Sets @self to be the union of @self and @other.
+ *
+ * That is, add all values from @other into @self that weren't part of it.
*
* It is allowed for @self and @other to be the same bitset. Nothing will
* happen in that case.
- **/
+ */
void
gtk_bitset_union (GtkBitset *self,
const GtkBitset *other)
@@ -557,15 +555,16 @@ gtk_bitset_union (GtkBitset *self,
/**
* gtk_bitset_intersect:
- * @self: a #GtkBitset
- * @other: the #GtkBitset to intersect with
+ * @self: a `GtkBitset`
+ * @other: the `GtkBitset` to intersect with
*
- * Sets @self to be the intersection of @self and @other, that is remove
- * all values from @self that are not part of @other.
+ * Sets @self to be the intersection of @self and @other.
+ *
+ * In other words, remove all values from @self that are not part of @other.
*
* It is allowed for @self and @other to be the same bitset. Nothing will
* happen in that case.
- **/
+ */
void
gtk_bitset_intersect (GtkBitset *self,
const GtkBitset *other)
@@ -581,15 +580,16 @@ gtk_bitset_intersect (GtkBitset *self,
/**
* gtk_bitset_subtract:
- * @self: a #GtkBitset
- * @other: the #GtkBitset to subtract
+ * @self: a `GtkBitset`
+ * @other: the `GtkBitset` to subtract
+ *
+ * Sets @self to be the subtraction of @other from @self.
*
- * Sets @self to be the subtraction of @other from @self, that is remove
- * all values from @self that are part of @other.
+ * In other words, remove all values from @self that are part of @other.
*
* It is allowed for @self and @other to be the same bitset. The bitset
* will be emptied in that case.
- **/
+ */
void
gtk_bitset_subtract (GtkBitset *self,
const GtkBitset *other)
@@ -608,17 +608,18 @@ gtk_bitset_subtract (GtkBitset *self,
/**
* gtk_bitset_difference:
- * @self: a #GtkBitset
- * @other: the #GtkBitset to compute the difference from
+ * @self: a `GtkBitset`
+ * @other: the `GtkBitset` to compute the difference from
+ *
+ * Sets @self to be the symmetric difference of @self and @other.
*
- * Sets @self to be the symmetric difference of @self and @other, that
- * is set @self to contain all values that were either contained in @self
- * or in @other, but not in both.
+ * The symmetric difference is set @self to contain all values that
+ * were either contained in @self or in @other, but not in both.
* This operation is also called an XOR.
*
* It is allowed for @self and @other to be the same bitset. The bitset
* will be emptied in that case.
- **/
+ */
void
gtk_bitset_difference (GtkBitset *self,
const GtkBitset *other)
@@ -637,12 +638,13 @@ gtk_bitset_difference (GtkBitset *self,
/**
* gtk_bitset_shift_left:
- * @self: a $GtkBitset
+ * @self: a `GtkBitset`
* @amount: amount to shift all values to the left
*
- * Shifts all values in @self to the left by @amount. Values
- * smaller than @amount are discarded.
- **/
+ * Shifts all values in @self to the left by @amount.
+ *
+ * Values smaller than @amount are discarded.
+ */
void
gtk_bitset_shift_left (GtkBitset *self,
guint amount)
@@ -672,12 +674,13 @@ gtk_bitset_shift_left (GtkBitset *self,
/**
* gtk_bitset_shift_right:
- * @self: a $GtkBitset
+ * @self: a `GtkBitset`
* @amount: amount to shift all values to the right
*
- * Shifts all values in @self to the right by @amount. Values
- * that end up too large to be held in a #guint are discarded.
- **/
+ * Shifts all values in @self to the right by @amount.
+ *
+ * Values that end up too large to be held in a #guint are discarded.
+ */
void
gtk_bitset_shift_right (GtkBitset *self,
guint amount)
@@ -707,13 +710,13 @@ gtk_bitset_shift_right (GtkBitset *self,
/**
* gtk_bitset_splice:
- * @self: a #GtkBitset
+ * @self: a `GtkBitset`
* @position: position at which to slice
* @removed: number of values to remove
* @added: number of values to add
*
- * This is a support function for #GListModel handling, by mirroring
- * the #GlistModel::items-changed signal.
+ * This is a support function for `GListModel` handling, by mirroring
+ * the `GlistModel::items-changed` signal.
*
* First, it "cuts" the values from @position to @removed from
* the bitset. That is, it removes all those values and shifts
@@ -722,7 +725,7 @@ gtk_bitset_shift_right (GtkBitset *self,
* Then, it "pastes" new room into the bitset by shifting all values
* larger than @position by @added spaces to the right. This frees
* up space that can then be filled.
- **/
+ */
void
gtk_bitset_splice (GtkBitset *self,
guint position,
@@ -755,16 +758,17 @@ G_STATIC_ASSERT (sizeof (GtkBitsetIter) >= sizeof (roaring_uint32_iterator_t));
/**
* gtk_bitset_iter_init_first:
- * @iter: (out): a pointer to an uninitialized #GtkBitsetIter
- * @set: a #GtkBitset
+ * @iter: (out): a pointer to an uninitialized `GtkBitsetIter`
+ * @set: a `GtkBitset`
* @value: (out) (optional): Set to the first value in @set
*
* Initializes an iterator for @set and points it to the first
- * value in @set. If @set is empty, %FALSE is returned and @value
- * is set to %G_MAXUINT.
+ * value in @set.
+ *
+ * If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT.
*
* Returns: %TRUE if @set isn't empty.
- **/
+ */
gboolean
gtk_bitset_iter_init_first (GtkBitsetIter *iter,
const GtkBitset *set,
@@ -785,12 +789,14 @@ gtk_bitset_iter_init_first (GtkBitsetIter *iter,
/**
* gtk_bitset_iter_init_last:
- * @iter: (out): a pointer to an uninitialized #GtkBitsetIter
- * @set: a #GtkBitset
+ * @iter: (out): a pointer to an uninitialized `GtkBitsetIter`
+ * @set: a `GtkBitset`
* @value: (out) (optional): Set to the last value in @set
*
* Initializes an iterator for @set and points it to the last
- * value in @set. If @set is empty, %FALSE is returned.
+ * value in @set.
+ *
+ * If @set is empty, %FALSE is returned.
*
* Returns: %TRUE if @set isn't empty.
**/
@@ -814,17 +820,18 @@ gtk_bitset_iter_init_last (GtkBitsetIter *iter,
/**
* gtk_bitset_iter_init_at:
- * @iter: (out): a pointer to an uninitialized #GtkBitsetIter
- * @set: a #GtkBitset
+ * @iter: (out): a pointer to an uninitialized `GtkBitsetIter`
+ * @set: a `GtkBitset`
* @target: target value to start iterating at
* @value: (out) (optional): Set to the found value in @set
*
- * Initializes @iter to point to @target. If @target is not found, finds
- * the next value after it. If no value >= @target exists in @set, this
- * function returns %FALSE.
+ * Initializes @iter to point to @target.
+ *
+ * If @target is not found, finds the next value after it.
+ * If no value >= @target exists in @set, this function returns %FALSE.
*
* Returns: %TRUE if a value was found.
- **/
+ */
gboolean
gtk_bitset_iter_init_at (GtkBitsetIter *iter,
const GtkBitset *set,
@@ -852,15 +859,16 @@ gtk_bitset_iter_init_at (GtkBitsetIter *iter,
/**
* gtk_bitset_iter_next:
- * @iter: a pointer to a valid #GtkBitsetIter
+ * @iter: a pointer to a valid `GtkBitsetIter`
* @value: (out) (optional): Set to the next value
*
- * Moves @iter to the next value in the set. If it was already
- * pointing to the last value in the set, %FALSE is returned and
- * @iter is invalidated.
+ * Moves @iter to the next value in the set.
+ *
+ * If it was already pointing to the last value in the set,
+ * %FALSE is returned and @iter is invalidated.
*
* Returns: %TRUE if a next value existed
- **/
+ */
gboolean
gtk_bitset_iter_next (GtkBitsetIter *iter,
guint *value)
@@ -884,15 +892,16 @@ gtk_bitset_iter_next (GtkBitsetIter *iter,
/**
* gtk_bitset_iter_previous:
- * @iter: a pointer to a valid #GtkBitsetIter
+ * @iter: a pointer to a valid `GtkBitsetIter`
* @value: (out) (optional): Set to the previous value
*
- * Moves @iter to the previous value in the set. If it was already
- * pointing to the first value in the set, %FALSE is returned and
- * @iter is invalidated.
+ * Moves @iter to the previous value in the set.
+ *
+ * If it was already pointing to the first value in the set,
+ * %FALSE is returned and @iter is invalidated.
*
* Returns: %TRUE if a previous value existed
- **/
+ */
gboolean
gtk_bitset_iter_previous (GtkBitsetIter *iter,
guint *value)
@@ -916,15 +925,15 @@ gtk_bitset_iter_previous (GtkBitsetIter *iter,
/**
* gtk_bitset_iter_get_value:
- * @iter: a #GtkBitsetIter
+ * @iter: a `GtkBitsetIter`
*
* Gets the current value that @iter points to.
*
- * If @iter is not valid and gtk_bitset_iter_is_valid() returns
- * %FALSE, this function returns 0.
+ * If @iter is not valid and [method@Gtk.BitsetIter.is_valid]
+ * returns %FALSE, this function returns 0.
*
* Returns: The current value pointer to by @iter
- **/
+ */
guint
gtk_bitset_iter_get_value (const GtkBitsetIter *iter)
{
@@ -940,12 +949,12 @@ gtk_bitset_iter_get_value (const GtkBitsetIter *iter)
/**
* gtk_bitset_iter_is_valid:
- * @iter: a #GtkBitsetIter
+ * @iter: a `GtkBitsetIter`
*
* Checks if @iter points to a valid value.
*
* Returns: %TRUE if @iter points to a valid value
- **/
+ */
gboolean
gtk_bitset_iter_is_valid (const GtkBitsetIter *iter)
{
diff --git a/gtk/gtkbitset.h b/gtk/gtkbitset.h
index 419b4df8d1..d85626b20e 100644
--- a/gtk/gtkbitset.h
+++ b/gtk/gtkbitset.h
@@ -134,10 +134,11 @@ void gtk_bitset_splice (GtkBitset
* GtkBitsetIter:
*
* An opaque, stack-allocated struct for iterating
- * over the elements of a #GtkBitset. Before a GtkBitsetIter
- * can be used, it needs to be initialized with
- * gtk_bitset_iter_init_first(), gtk_bitset_iter_init_last()
- * or gtk_bitset_iter_init_at().
+ * over the elements of a `GtkBitset`.
+ *
+ * Before a `GtkBitsetIter` can be used, it needs to be initialized with
+ * [func@Gtk.BitsetIter.init_first], [func@Gtk.BitsetIter.init_last]
+ * or [func@Gtk.BitsetIter.init_at].
*/
typedef struct _GtkBitsetIter GtkBitsetIter;
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]