From: Karel Zak <kzak@redhat.com>
Date: Thu, 14 Aug 2014 19:04:01 +0000 (+0200)
Subject: libfdisk: more docs
X-Git-Tag: v2.26-rc1~511
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5175ae87384e3136497c33ffa7bd1b2c2e14af2e;p=thirdparty%2Futil-linux.git

libfdisk: more docs

Signed-off-by: Karel Zak <kzak@redhat.com>
---

diff --git a/libfdisk/src/alignment.c b/libfdisk/src/alignment.c
index e715d111ab..9e1e722c87 100644
--- a/libfdisk/src/alignment.c
+++ b/libfdisk/src/alignment.c
@@ -6,6 +6,12 @@
 
 #include "fdiskP.h"
 
+/**
+ * SECTION: alignment
+ * @title: Align LBA
+ * @short_description: function to align partitions and work with disk topology and geometry.
+ */
+
 /*
  * Alignment according to logical granulity (usually 1MiB)
  */
diff --git a/libfdisk/src/context.c b/libfdisk/src/context.c
index c6e99eef4c..48dfe85caf 100644
--- a/libfdisk/src/context.c
+++ b/libfdisk/src/context.c
@@ -4,6 +4,33 @@
 
 #include "fdiskP.h"
 
+
+/**
+ * SECTION: context
+ * @title: libfdisk handler
+ * @short_description: stores infor about device, labels etc.
+ *
+ * Partitioning data:
+ *
+ * on-disk data
+ *    The libfdisk reads PT when you assign device to the context, the
+ *    function fdisk_write_disklabel() modify on-disk data.
+ *
+ * in-memory data
+ *    All data are label specific, but usually stored in the first sector
+ *    which is cached in memory and shared between all label drivers (see
+ *    labelsection for more details). All label operations are based on
+ *    in-memory data.
+ *
+ * struct fdisk_partition
+ *    The struct provides abstraction to present partitions to users (for
+ *    example to generate human readable info about PT) and it's also unified
+ *    way how to define partition template that can be used by label driver to
+ *    create a new partition. It's necessary to understand the struct
+ *    fdisk_partition is always completely independent object and any change to
+ *    the object has no effect to in-memory (or on-disk) label data.
+ */
+
 /**
  * fdisk_new_context:
  *
@@ -200,7 +227,9 @@ int __fdisk_switch_label(struct fdisk_context *cxt, struct fdisk_label *lb)
  * @cxt: context
  * @name: label name (e.g. "gpt")
  *
- * Forces libfdisk to use the label driver.
+ * Forces libfdisk to use the label driver. It's usually bad idea to use this
+ * function, it's better to use fdisk_create_disklabel().
+ *
  *
  * Returns: 0 on succes, <0 in case of error.
  */
@@ -225,6 +254,8 @@ int fdisk_has_label(struct fdisk_context *cxt)
  * @cxt: fdisk context
  * @l: disklabel type
  *
+ * See also fdisk_is_label() macro in libfdisk.h.
+ * 
  * Returns: return 1 if there is @l disklabel on the device.
  */
 int fdisk_is_labeltype(struct fdisk_context *cxt, enum fdisk_labeltype l)
@@ -319,7 +350,8 @@ static int warn_wipe(struct fdisk_context *cxt)
  * @fname: path to the device to be handled
  * @readonly: how to open the device
  *
- * Open the device, discovery topology, geometry, and detect disklabel.
+ * Open the device, discovery topology, geometry, detect disklabel and
+ * switch the current label driver to reflect the probing result.
  *
  * Returns: 0 on success, < 0 on error.
  */
@@ -370,6 +402,13 @@ fail:
 	return -errno;
 }
 
+/**
+ * fdisk_deassign_device:
+ * @cxt: context
+ * @nosync: disable fsync()
+ *
+ * Close device and call fsync()
+ */
 int fdisk_deassign_device(struct fdisk_context *cxt, int nosync)
 {
 	assert(cxt);
@@ -392,6 +431,12 @@ int fdisk_deassign_device(struct fdisk_context *cxt, int nosync)
 	return 0;
 }
 
+/**
+ * fdisk_is_readonly:
+ * @cxt: context
+ *
+ * Returns: 1 if device open readonly
+ */
 int fdisk_is_readonly(struct fdisk_context *cxt)
 {
 	assert(cxt);
diff --git a/libfdisk/src/label.c b/libfdisk/src/label.c
index c8691b6db3..4e37f74f99 100644
--- a/libfdisk/src/label.c
+++ b/libfdisk/src/label.c
@@ -2,8 +2,25 @@
 #include "fdiskP.h"
 
 
-/*
- * Don't use this function derectly
+/**
+ * SECTION: label
+ * @title: Label specific driver
+ * @short_description: label (PT) specific data and functions
+ *
+ * The fdisk_new_context() initializes all label drivers, and allocate
+ * per-label specific data struct. This concept allows to store label specific
+ * settings to the label driver independently on the currently active label
+ * driver.
+ *
+ * Anyway, all label drives share in-memory first sector. The function
+ * fdisk_create_disklabel() overwrites the sector. But it's possible that
+ * label driver also uses another buffers, for example GPT uses more than only
+ * the first sector.
+ *
+ * All label operations are in-memory only, except fdisk_write_disklabel().
+ *
+ * All functions that use "struct fdisk_context" rather than "struct
+ * fdisk_label" use the currently active label driver.
  */
 int fdisk_probe_labels(struct fdisk_context *cxt)
 {
@@ -123,6 +140,17 @@ int fdisk_label_get_fields_ids(
 	return 0;
 }
 
+/**
+ * fdisk_label_get_field:
+ * @lb: label
+ * @id: FDISK_FIELD_*
+ *
+ * The field struct describes data stored in struct fdisk_partition. The info
+ * about data is usable for example to generate human readable output (e.g.
+ * fdisk 'p'rint command). See fdisk_partition_to_stirng() and fdisk code.
+ *
+ * Returns: pointer to static instance of the field.
+ */
 const struct fdisk_field *fdisk_label_get_field(struct fdisk_label *lb, int id)
 {
 	size_t i;
@@ -138,21 +166,45 @@ const struct fdisk_field *fdisk_label_get_field(struct fdisk_label *lb, int id)
 	return NULL;
 }
 
+/**
+ * fdisk_field_get_id:
+ * @field: field instance
+ *
+ * Returns: field Id (FDISK_FIELD_*)
+ */
 int fdisk_field_get_id(const struct fdisk_field *field)
 {
 	return field ? field->id : -EINVAL;
 }
 
+/**
+ * fdisk_field_get_name:
+ * @field: field instance
+ *
+ * Returns: field name
+ */
 const char *fdisk_field_get_name(const struct fdisk_field *field)
 {
 	return field ? field->name : NULL;
 }
 
+/**
+ * fdisk_field_get_width:
+ * @field: field instance
+ *
+ * Returns: libsmartcols compatible width.
+ */
 double fdisk_field_get_width(const struct fdisk_field *field)
 {
 	return field ? field->width : -EINVAL;
 }
 
+/**
+ * fdisk_field_is_number:
+ * @field: field instance
+ *
+ * Returns: 1 if field represent number
+ */
 int fdisk_field_is_number(const struct fdisk_field *field)
 {
 	return field->flags ? field->flags & FDISK_FIELDFL_NUMBER : 0;
@@ -163,7 +215,7 @@ int fdisk_field_is_number(const struct fdisk_field *field)
  * fdisk_write_disklabel:
  * @cxt: fdisk context
  *
- * Write in-memory changes to disk
+ * Write in-memory changes to disk. Be careful!
  *
  * Returns 0 on success, otherwise, a corresponding error.
  */
@@ -222,8 +274,12 @@ int fdisk_list_disklabel(struct fdisk_context *cxt)
  * @cxt: fdisk context
  * @name: label name
  *
- * Creates a new disk label of type @name. If @name is NULL, then it
- * will create a default system label type, either SUN or DOS.
+ * Creates a new disk label of type @name. If @name is NULL, then it will
+ * create a default system label type, either SUN or DOS. The function
+ * automaticaly switches the current label driver to @name. The function
+ * fdisk_get_label() returns the current label driver.
+ *
+ * The function modifies in-memory data only.
  *
  * Returns 0 on success, otherwise, a corresponding error.
  */
@@ -293,7 +349,7 @@ int fdisk_locate_disklabel(struct fdisk_context *cxt, int n, const char **name,
 /**
  * fdisk_get_disklabel_id:
  * @cxt: fdisk context
- * @id: returns pointer to allocated string
+ * @id: returns pointer to allocated string (MBR Id or GPT dirk UUID)
  *
  * Returns 0 on success, otherwise, a corresponding error.
  */
@@ -402,18 +458,40 @@ void fdisk_deinit_label(struct fdisk_label *lb)
 		lb->op->deinit(lb);
 }
 
+/**
+ * fdisk_label_set_changed:
+ * @lb: label
+ * @changed: 0/1
+ *
+ * Marks in-memory data as changed, to force fdisk_write_disklabel() to write
+ * to device. This should be unnecessar by default, the library keeps track
+ * about changes.
+ */
 void fdisk_label_set_changed(struct fdisk_label *lb, int changed)
 {
 	assert(lb);
 	lb->changed = changed ? 1 : 0;
 }
 
+/**
+ * fdisk_label_is_changed:
+ * @lb: label
+ *
+ * Returns: 1 if in-memory data has been changed.
+ */
 int fdisk_label_is_changed(struct fdisk_label *lb)
 {
 	assert(lb);
 	return lb ? lb->changed : 0;
 }
 
+/**
+ * fdisk_label_set_disabled:
+ * @lb: label
+ *
+ * Mark label as disabled, then libfdisk is going to ignore the label when 
+ * probe device for labels.
+ */
 void fdisk_label_set_disabled(struct fdisk_label *lb, int disabled)
 {
 	assert(lb);
@@ -424,6 +502,12 @@ void fdisk_label_set_disabled(struct fdisk_label *lb, int disabled)
 	lb->disabled = disabled ? 1 : 0;
 }
 
+/**
+ * fdisk_label_is_disabled:
+ * @lb: label
+ *
+ * Returns: 1 if label driver disabled.
+ */
 int fdisk_label_is_disabled(struct fdisk_label *lb)
 {
 	assert(lb);
diff --git a/libfdisk/src/partition.c b/libfdisk/src/partition.c
index 5136e534be..48e91cf293 100644
--- a/libfdisk/src/partition.c
+++ b/libfdisk/src/partition.c
@@ -4,6 +4,11 @@
 
 #include "fdiskP.h"
 
+/**
+ * fdisk_new_partition:
+ *
+ * Returns: new instance.
+ */
 struct fdisk_partition *fdisk_new_partition(void)
 {
 	struct fdisk_partition *pa = calloc(1, sizeof(*pa));
@@ -16,6 +21,12 @@ struct fdisk_partition *fdisk_new_partition(void)
 	return pa;
 }
 
+/**
+ * fdisk_reset_partition:
+ * @pa: partition
+ *
+ * Resets partition content.
+ */
 void fdisk_reset_partition(struct fdisk_partition *pa)
 {
 	int ref;
@@ -36,12 +47,25 @@ void fdisk_reset_partition(struct fdisk_partition *pa)
 	INIT_LIST_HEAD(&pa->parts);
 }
 
+/**
+ * fdisk_ref_partition:
+ * @tb: partition pointer
+ *
+ * Incremparts reference counter.
+ */
 void fdisk_ref_partition(struct fdisk_partition *pa)
 {
 	if (pa)
 		pa->refcount++;
 }
 
+/**
+ * fdisk_unref_partition:
+ * @tb: partition pointer
+ *
+ * De-incremparts reference counter, on zero the @tb is automatically
+ * deallocated.
+ */
 void fdisk_unref_partition(struct fdisk_partition *pa)
 {
 	if (!pa)
@@ -80,6 +104,13 @@ int fdisk_dump_partition(struct fdisk_partition *pa, FILE *f)
 	return 0;
 }
 
+/**
+ * fdisk_partition_set_start:
+ * @pa: partition
+ * @off: offset in sectors
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_set_start(struct fdisk_partition *pa, uint64_t off)
 {
 	if (!pa)
@@ -88,17 +119,40 @@ int fdisk_partition_set_start(struct fdisk_partition *pa, uint64_t off)
 	return 0;
 }
 
+/**
+ * fdisk_partition_get_start:
+ * @pa: partition
+ *
+ * Returns: start offset in sectors
+ */
 uint64_t fdisk_partition_get_start(struct fdisk_partition *pa)
 {
 	return pa ? pa->start : 0;
 }
 
+/**
+ * fdisk_partition_cmp_start:
+ * @a: partition
+ * @b: partition
+ * See fdisk_sort_table().
+ */
 int fdisk_partition_cmp_start(struct fdisk_partition *a,
 			      struct fdisk_partition *b)
 {
 	return a->start - b->start;
 }
 
+/**
+ * fdisk_partition_set_end:
+ * @pa: partition
+ * @off: offset in sectors
+ *
+ * Sets end offset, and zeroize size.
+ *
+ * The usual way is to address end of the partition by fdisk_partition_set_size().
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_set_end(struct fdisk_partition *pa, uint64_t off)
 {
 	if (!pa)
@@ -108,12 +162,26 @@ int fdisk_partition_set_end(struct fdisk_partition *pa, uint64_t off)
 	return 0;
 }
 
+/**
+ * fdisk_partition_get_start:
+ * @pa: partition
+ *
+ * Returns: start offset in sectors
+ */
 uint64_t fdisk_partition_get_end(struct fdisk_partition *pa)
 {
 	return pa ? pa->end : 0;
 }
 
-
+/**
+ * fdisk_partition_set_size
+ * @pa: partition
+ * @size: in bytes
+ *
+ * Sets size, zeroize end offset. See also fdisk_partition_set_end().
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_set_size(struct fdisk_partition *pa, uint64_t size)
 {
 	if (!pa)
@@ -123,11 +191,27 @@ int fdisk_partition_set_size(struct fdisk_partition *pa, uint64_t size)
 	return 0;
 }
 
+/**
+ * fdisk_partition_get_start:
+ * @pa: partition
+ *
+ * Returns: size in sectors
+ */
 uint64_t fdisk_partition_get_size(struct fdisk_partition *pa)
 {
 	return pa ? pa->size : 0;
 }
 
+/**
+ * fdisk_partition_set_partno
+ * @pa: partition
+ * @n: partitiion number
+ *
+ * When @pa used as a tempalate for fdisk_add_partition() when infor label driver 
+ * about wanted partition position.
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_set_partno(struct fdisk_partition *pa, size_t n)
 {
 	if (!pa)
@@ -198,6 +282,16 @@ int fdisk_partition_set_uuid(struct fdisk_partition *pa, const char *uuid)
 	return 0;
 }
 
+/**
+ * fdisk_partition_partno_follow_default
+ * @pa: partition
+ * @enable: 0|1
+ *
+ * When @pa used as a tempalate for fdisk_add_partition() when force label driver
+ * to add a new partition to the default (next) position.
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_partno_follow_default(struct fdisk_partition *pa, int enable)
 {
 	if (!pa)
@@ -206,6 +300,16 @@ int fdisk_partition_partno_follow_default(struct fdisk_partition *pa, int enable
 	return 0;
 }
 
+/**
+ * fdisk_partition_start_follow_default
+ * @pa: partition
+ * @enable: 0|1
+ *
+ * When @pa used as a tempalate for fdisk_add_partition() when force label driver
+ * to use the first possible space for the new partition.
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_start_follow_default(struct fdisk_partition *pa, int enable)
 {
 	if (!pa)
@@ -214,6 +318,16 @@ int fdisk_partition_start_follow_default(struct fdisk_partition *pa, int enable)
 	return 0;
 }
 
+/**
+ * fdisk_partition_start_follow_default
+ * @pa: partition
+ * @enable: 0|1
+ *
+ * When @pa used as a tempalate for fdisk_add_partition() when force label driver
+ * to use all the possible space for the new partition.
+ *
+ * Returns: 0 on success, <0 on error.
+ */
 int fdisk_partition_end_follow_default(struct fdisk_partition *pa, int enable)
 {
 	if (!pa)
diff --git a/libfdisk/src/table.c b/libfdisk/src/table.c
index 61876d0efa..eb09838956 100644
--- a/libfdisk/src/table.c
+++ b/libfdisk/src/table.c
@@ -67,7 +67,7 @@ void fdisk_ref_table(struct fdisk_table *tb)
  * @tb: table pointer
  *
  * De-incremparts reference counter, on zero the @tb is automatically
- * deallocated by fdisk_free_table().
+ * deallocated.
  */
 void fdisk_unref_table(struct fdisk_table *tb)
 {
@@ -324,6 +324,13 @@ static int cmp_parts_wrapper(struct list_head *a, struct list_head *b, void *dat
 	return cmp(pa, pb);
 }
 
+/**
+ * fdisk_table_sort_partitions:
+ * @tb: table
+ * @cmp: compare function
+ *
+ * Sort partition in the table.
+ */
 int fdisk_table_sort_partitions(struct fdisk_table *tb,
 			int (*cmp)(struct fdisk_partition *,
 				   struct fdisk_partition *))
@@ -461,8 +468,7 @@ static int check_container_freespace(struct fdisk_context *cxt,
  * This function adds freespace (described by fdisk_partition) to @table, it
  * allocates a new table if the @table points to NULL.
  *
- * Note that free space smaller than grain (see fdisk_topology_get_grain()) is
- * ignored.
+ * Note that free space smaller than grain (see fdisk_get_grain()) is ignored.
 
  * Returns 0 on success, otherwise, a corresponding error.
  */