From 705854f30773e463cd61796bc896f0c0053aa36d Mon Sep 17 00:00:00 2001 From: Karel Zak Date: Wed, 26 Nov 2014 19:13:57 +0100 Subject: [PATCH] libfdisk: add API docs Signed-off-by: Karel Zak --- configure.ac | 4 +- libfdisk/Makemodule.am | 5 + libfdisk/docs/.gitignore | 18 ++ libfdisk/docs/Makefile.am | 93 +++++++++ libfdisk/docs/libfdisk-docs.xml | 62 ++++++ libfdisk/docs/libfdisk-sections.txt | 301 ++++++++++++++++++++++++++++ libfdisk/docs/version.xml.in | 1 + libfdisk/src/alignment.c | 8 +- libfdisk/src/ask.c | 15 +- libfdisk/src/bsd.c | 4 +- libfdisk/src/context.c | 11 +- libfdisk/src/dos.c | 4 +- libfdisk/src/gpt.c | 4 +- libfdisk/src/label.c | 28 +-- libfdisk/src/libfdisk.h.in | 12 +- libfdisk/src/partition.c | 12 +- libfdisk/src/parttype.c | 4 +- libfdisk/src/script.c | 13 +- libfdisk/src/sgi.c | 4 +- libfdisk/src/sun.c | 4 +- libfdisk/src/table.c | 8 +- libfdisk/src/utils.c | 4 +- 22 files changed, 557 insertions(+), 62 deletions(-) create mode 100644 libfdisk/docs/.gitignore create mode 100644 libfdisk/docs/Makefile.am create mode 100644 libfdisk/docs/libfdisk-docs.xml create mode 100644 libfdisk/docs/libfdisk-sections.txt create mode 100644 libfdisk/docs/version.xml.in diff --git a/configure.ac b/configure.ac index 80fcb4d8a..b3b6b9f51 100644 --- a/configure.ac +++ b/configure.ac @@ -1859,13 +1859,15 @@ Makefile libblkid/docs/Makefile libblkid/docs/version.xml libblkid/src/blkid.h +libfdisk/docs/Makefile +libfdisk/docs/version.xml +libfdisk/src/libfdisk.h libmount/docs/Makefile libmount/docs/version.xml libmount/src/libmount.h libsmartcols/docs/Makefile libsmartcols/docs/version.xml libsmartcols/src/libsmartcols.h -libfdisk/src/libfdisk.h po/Makefile.in ]) diff --git a/libfdisk/Makemodule.am b/libfdisk/Makemodule.am index 5efcac5cc..5d8334164 100644 --- a/libfdisk/Makemodule.am +++ b/libfdisk/Makemodule.am @@ -2,6 +2,11 @@ if BUILD_LIBFDISK include libfdisk/src/Makemodule.am +if ENABLE_GTK_DOC +# Docs uses separate Makefiles +SUBDIRS += libfdisk/docs +endif + pkgconfig_DATA += libfdisk/fdisk.pc PATHFILES += libfdisk/fdisk.pc EXTRA_DIST += libfdisk/COPYING diff --git a/libfdisk/docs/.gitignore b/libfdisk/docs/.gitignore new file mode 100644 index 000000000..f91f93db7 --- /dev/null +++ b/libfdisk/docs/.gitignore @@ -0,0 +1,18 @@ +*-decl-list.txt +*-decl.txt +*-overrides.txt +*-undeclared.txt +*-undocumented.txt +*-unused.txt +*.args +*.bak +*.hierarchy +*.interfaces +*.prerequisites +*.signals +*.stamp +*.types +html/* +tmpl/* +version.xml +xml/* diff --git a/libfdisk/docs/Makefile.am b/libfdisk/docs/Makefile.am new file mode 100644 index 000000000..dc7097995 --- /dev/null +++ b/libfdisk/docs/Makefile.am @@ -0,0 +1,93 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.10 at least. +AUTOMAKE_OPTIONS = 1.10 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=libfdisk + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=../src + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml +MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space fdisk + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB=$(top_builddir)/libfdisk/src/libfdisk.h +CFILE_GLOB=$(top_srcdir)/libfdisk/src/*.c + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files to ignore when scanning. Use base file name, no paths +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h +IGNORE_HFILES=fdiskP.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files = $(builddir)/version.xml + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/config/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += version.xml.in + +# Files not to distribute +# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types +# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt +DISTCLEANFILES += version.xml diff --git a/libfdisk/docs/libfdisk-docs.xml b/libfdisk/docs/libfdisk-docs.xml new file mode 100644 index 000000000..546d007a7 --- /dev/null +++ b/libfdisk/docs/libfdisk-docs.xml @@ -0,0 +1,62 @@ + + +]> + + + libfdisk Reference Manual + for libfdisk version &version; + + 2014 + Karel Zak <kzak@redhat.com> + + + + + libfdisk Overview + + +The libfdisk library is used for manipulating with partition tables. + + +The library is part of the util-linux package since version 2.26 and is +available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/. + + + + + + Basic handlers and setting + + + + + + + Partitining + + + + + + + Label specific functions + + + + + + + + Misc + + + + + + API Index + + + diff --git a/libfdisk/docs/libfdisk-sections.txt b/libfdisk/docs/libfdisk-sections.txt new file mode 100644 index 000000000..2dff5c998 --- /dev/null +++ b/libfdisk/docs/libfdisk-sections.txt @@ -0,0 +1,301 @@ +
+init +fdisk_init_debug +
+ +
+ask +fdisk_info +fdisk_warn +fdisk_warnx +fdisk_set_ask + +fdisk_ask +fdisk_ask_get_query +fdisk_ask_get_type +fdisk_ask_menu_get_default +fdisk_ask_menu_get_item +fdisk_ask_menu_get_nitems +fdisk_ask_menu_get_result +fdisk_ask_menu_set_result +fdisk_ask_number +fdisk_ask_number_get_base +fdisk_ask_number_get_default +fdisk_ask_number_get_high +fdisk_ask_number_get_low +fdisk_ask_number_get_range +fdisk_ask_number_get_result +fdisk_ask_number_get_unit +fdisk_ask_number_inchars +fdisk_ask_number_set_relative +fdisk_ask_number_set_result +fdisk_ask_partnum +fdisk_ask_print_get_errno +fdisk_ask_print_get_mesg +fdisk_ask_string +fdisk_ask_string_get_result +fdisk_ask_string_set_result +fdisk_ask_yesno +fdisk_ask_yesno_get_result +fdisk_ask_yesno_set_result +fdisk_ref_ask +fdisk_unref_ask +
+ +
+alignment +fdisk_align_lba +fdisk_align_lba_in_range +fdisk_has_user_device_properties +fdisk_lba_is_phy_aligned +fdisk_override_geometry +fdisk_reread_partition_table +fdisk_reset_alignment +fdisk_reset_device_properties +fdisk_save_user_geometry +fdisk_save_user_sector_size +
+ +
+label +fdisk_create_disklabel +fdisk_list_disklabel +fdisk_locate_disklabel +fdisk_reorder_partitions +fdisk_set_disklabel_id +fdisk_set_partition_type +fdisk_toggle_partition_flag +fdisk_verify_disklabel +fdisk_write_disklabel + +fdisk_get_disklabel_id +fdisk_get_label +fdisk_get_nlabels +fdisk_next_label +fdisk_get_npartitions + +fdisk_field +fdisk_field_get_id +fdisk_field_get_name +fdisk_field_get_width +fdisk_field_is_number + +fdisk_label +fdisk_label_get_field +fdisk_label_get_field_by_name +fdisk_label_get_fields_ids +fdisk_label_get_name +fdisk_label_get_nparttypes +fdisk_label_get_parttype +fdisk_label_get_parttype_from_code +fdisk_label_get_parttype_from_string +fdisk_label_get_type +fdisk_label_has_code_parttypes +fdisk_label_is_changed +fdisk_label_is_disabled +fdisk_label_parse_parttype +fdisk_label_require_geometry +fdisk_label_set_changed +fdisk_label_set_disabled +
+ +
+script +fdisk_set_script +fdisk_get_script + +fdisk_apply_script +fdisk_apply_script_headers + +fdisk_script +fdisk_new_script +fdisk_new_script_from_file +fdisk_ref_script +fdisk_script_get_header +fdisk_script_get_nlines +fdisk_script_get_table +fdisk_script_read_context +fdisk_script_read_file +fdisk_script_read_line +fdisk_script_set_header +fdisk_script_write_file +fdisk_unref_script +
+ +
+bsd +fdisk_bsd_edit_disklabel +fdisk_bsd_link_partition +fdisk_bsd_write_bootstrap +
+ +
+partition +fdisk_add_partition +fdisk_delete_all_partitions +fdisk_delete_partition +fdisk_get_partition +fdisk_is_partition_used +fdisk_set_partition + +fdisk_partition +fdisk_new_partition +fdisk_partition_cmp_partno +fdisk_partition_cmp_start +fdisk_partition_end_follow_default +fdisk_partition_end_is_default +fdisk_partition_get_attrs +fdisk_partition_get_name +fdisk_partition_get_parent +fdisk_partition_get_partno +fdisk_partition_get_size +fdisk_partition_get_start +fdisk_partition_get_type +fdisk_partition_get_uuid +fdisk_partition_has_partno +fdisk_partition_has_size +fdisk_partition_has_start +fdisk_partition_is_bootable +fdisk_partition_is_container +fdisk_partition_is_freespace +fdisk_partition_is_nested +fdisk_partition_is_used +fdisk_partition_next_partno +fdisk_partition_partno_follow_default +fdisk_partition_set_attrs +fdisk_partition_set_name +fdisk_partition_set_partno +fdisk_partition_set_size +fdisk_partition_set_start +fdisk_partition_set_type +fdisk_partition_set_uuid +fdisk_partition_size_explicit +fdisk_partition_start_follow_default +fdisk_partition_start_is_default +fdisk_partition_to_string +fdisk_partition_unset_partno +fdisk_partition_unset_size +fdisk_partition_unset_start +fdisk_ref_partition +fdisk_reset_partition +fdisk_unref_partition +
+ +
+dos +fdisk_dos_enable_compatible +fdisk_dos_is_compatible +fdisk_dos_move_begin +
+ +
+sgi +fdisk_sgi_create_info +fdisk_sgi_set_bootfile +
+ +
+gpt +fdisk_gpt_is_hybrid +
+ +
+sun +fdisk_sun_set_alt_cyl +fdisk_sun_set_ilfact +fdisk_sun_set_pcylcount +fdisk_sun_set_rspeed +fdisk_sun_set_xcyl +
+ +
+parttype +fdisk_parttype +fdisk_copy_parttype +fdisk_new_parttype +fdisk_new_unknown_parttype +fdisk_parttype_get_code +fdisk_parttype_get_name +fdisk_parttype_get_string +fdisk_parttype_is_unknown +fdisk_parttype_set_code +fdisk_parttype_set_name +fdisk_parttype_set_typestr +fdisk_ref_parttype +fdisk_unref_parttype +
+ +
+table +fdisk_get_freespaces +fdisk_get_partitions + +fdisk_table +fdisk_apply_table +fdisk_new_table +fdisk_ref_table +fdisk_reset_table +fdisk_table_add_partition +fdisk_table_get_nents +fdisk_table_get_partition +fdisk_table_is_empty +fdisk_table_next_partition +fdisk_table_remove_partition +fdisk_table_sort_partitions +fdisk_table_wrong_order +fdisk_unref_table +
+ + +
+context +fdisk_context +fdisk_assign_device +fdisk_deassign_device +fdisk_enable_details +fdisk_enable_listonly +fdisk_get_alignment_offset +fdisk_get_devfd +fdisk_get_devname +fdisk_get_first_lba +fdisk_get_geom_cylinders +fdisk_get_geom_heads +fdisk_get_geom_sectors +fdisk_get_grain_size +fdisk_get_last_lba +fdisk_get_minimal_iosize +fdisk_get_nsectors +fdisk_get_optimal_iosize +fdisk_get_parent +fdisk_get_physector_size +fdisk_get_sector_size +fdisk_get_unit +fdisk_get_units_per_sector +fdisk_has_label +fdisk_has_user_device_properties +fdisk_is_details +fdisk_is_labeltype +fdisk_is_listonly +fdisk_is_readonly +fdisk_new_context +fdisk_new_nested_context +fdisk_ref_context +fdisk_set_first_lba +fdisk_set_last_lba +fdisk_set_unit +fdisk_unref_context +fdisk_use_cylinders +
+ +
+utils +fdisk_partname +
+ +
+iter +fdisk_free_iter +fdisk_iter_get_direction +fdisk_new_iter +fdisk_reset_iter +
diff --git a/libfdisk/docs/version.xml.in b/libfdisk/docs/version.xml.in new file mode 100644 index 000000000..d78bda934 --- /dev/null +++ b/libfdisk/docs/version.xml.in @@ -0,0 +1 @@ +@VERSION@ diff --git a/libfdisk/src/alignment.c b/libfdisk/src/alignment.c index 90f21bc69..93cb80b32 100644 --- a/libfdisk/src/alignment.c +++ b/libfdisk/src/alignment.c @@ -8,8 +8,8 @@ /** * SECTION: alignment - * @title: Align LBA - * @short_description: function to align partitions and work with disk topology and geometry. + * @title: Alignment + * @short_description: functions to align partitions and work with disk topology and geometry * * The libfdisk aligns the end of the partitions to make it possible to align * the next partition to the "grain" (see fdisk_get_grain()). The grain is @@ -233,8 +233,8 @@ int fdisk_override_geometry(struct fdisk_context *cxt, * fdisk_save_user_geometry: * @cxt: context * @cylinders: C - * @head: H - * @sector: S + * @heads: H + * @sectors: S * * Save user defined geometry to use it for partitioning. * diff --git a/libfdisk/src/ask.c b/libfdisk/src/ask.c index 57c01ae23..647687ef8 100644 --- a/libfdisk/src/ask.c +++ b/libfdisk/src/ask.c @@ -4,8 +4,8 @@ /** * SECTION: ask - * @title: Ask callback - * @short_description: interface for dialog driven partitioning + * @title: Ask + * @short_description: interface for dialog driven partitioning, warning and info messages * */ @@ -198,7 +198,7 @@ int fdisk_ask_number_set_default(struct fdisk_ask *ask, uint64_t dflt) } /** - * fdisk_ask_number_get_low" + * fdisk_ask_number_get_low: * @ask: ask instance * * Returns: minimal possible number when ask for numbers in range @@ -218,7 +218,7 @@ int fdisk_ask_number_set_low(struct fdisk_ask *ask, uint64_t low) } /** - * fdisk_ask_number_get_high" + * fdisk_ask_number_get_high: * @ask: ask instance * * Returns: maximal possible number when ask for numbers in range @@ -253,7 +253,7 @@ uint64_t fdisk_ask_number_get_result(struct fdisk_ask *ask) /** * fdisk_ask_number_set_result: * @ask: ask instance - * @ask: dialog result + * @result: dialog result * * Returns: 0 on success, <0 on error */ @@ -268,7 +268,7 @@ int fdisk_ask_number_set_result(struct fdisk_ask *ask, uint64_t result) * fdisk_ask_number_get_base: * @ask: ask instance * - * Returns: base when user specify number in relative notation (+) + * Returns: base when user specify number in relative notation (+size) */ uint64_t fdisk_ask_number_get_base(struct fdisk_ask *ask) { @@ -923,6 +923,7 @@ static int do_vprint(struct fdisk_context *cxt, int errnum, int type, * fdisk_info: * @cxt: context * @fmt: printf-like formatted string + * @...: variable parametrs * * High-level API to print info messages, * @@ -944,6 +945,7 @@ int fdisk_info(struct fdisk_context *cxt, const char *fmt, ...) * fdisk_info: * @cxt: context * @fmt: printf-like formatted string + * @...: variable parametrs * * High-level API to print warning message (errno expected) * @@ -965,6 +967,7 @@ int fdisk_warn(struct fdisk_context *cxt, const char *fmt, ...) * fdisk_warnx: * @cxt: context * @fmt: printf-like formatted string + * @...: variable options * * High-level API to print warning message * diff --git a/libfdisk/src/bsd.c b/libfdisk/src/bsd.c index ab8cecfb8..d355cc0aa 100644 --- a/libfdisk/src/bsd.c +++ b/libfdisk/src/bsd.c @@ -26,8 +26,8 @@ /** * SECTION: bsd - * @title: BSD functions - * @short_description: BSD disklabel specific libfdisk functions + * @title: BSD + * @short_description: disk label specific functions * */ diff --git a/libfdisk/src/context.c b/libfdisk/src/context.c index 3e82f071b..42ad9f8a9 100644 --- a/libfdisk/src/context.c +++ b/libfdisk/src/context.c @@ -7,8 +7,8 @@ /** * SECTION: context - * @title: libfdisk handler - * @short_description: stores infor about device, labels etc. + * @title: Context + * @short_description: stores info about device, labels etc. * * The library distinguish between three types of partitioning objects. * @@ -346,7 +346,7 @@ size_t fdisk_get_npartitions(struct fdisk_context *cxt) * * See also fdisk_is_label() macro in libfdisk.h. * - * Returns: return 1 if the current label is @l + * Returns: return 1 if the current label is @id */ int fdisk_is_labeltype(struct fdisk_context *cxt, enum fdisk_labeltype id) { @@ -724,6 +724,7 @@ int fdisk_set_unit(struct fdisk_context *cxt, const char *str) /** * fdisk_get_unit: * @cxt: context + * @n: FDISK_PLURAL or FDISK_SINGULAR * * Returns: unit name. */ @@ -738,9 +739,9 @@ const char *fdisk_get_unit(struct fdisk_context *cxt, int n) /** * fdisk_use_cylinders: - * @@cxt: context + * @cxt: context * - * Returns 1 if user wants to display in cylinders. + * Returns: 1 if user wants to display in cylinders. */ int fdisk_use_cylinders(struct fdisk_context *cxt) { diff --git a/libfdisk/src/dos.c b/libfdisk/src/dos.c index 44459fa48..abafcc248 100644 --- a/libfdisk/src/dos.c +++ b/libfdisk/src/dos.c @@ -21,8 +21,8 @@ /** * SECTION: dos - * @title: MBR (DOS) functions - * @short_description: MBR disk label specific functions + * @title: DOS (MBR) + * @short_description: disk label specific functions * */ diff --git a/libfdisk/src/gpt.c b/libfdisk/src/gpt.c index 52ded7ddc..6448a054a 100644 --- a/libfdisk/src/gpt.c +++ b/libfdisk/src/gpt.c @@ -30,8 +30,8 @@ /** * SECTION: gpt - * @title: UEFI GPT functions - * @short_description: GPT specific functionality + * @title: UEFI GPT + * @short_description: specific functionality */ #define GPT_HEADER_SIGNATURE 0x5452415020494645LL /* EFI PART */ diff --git a/libfdisk/src/label.c b/libfdisk/src/label.c index ff3b48967..750cfca55 100644 --- a/libfdisk/src/label.c +++ b/libfdisk/src/label.c @@ -4,8 +4,8 @@ /** * SECTION: label - * @title: Label specific driver - * @short_description: label (PT) specific data and functions + * @title: Label + * @short_description: disk 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 @@ -101,6 +101,7 @@ int fdisk_label_require_geometry(const struct fdisk_label *lb) /** * fdisk_label_get_fields_ids * @lb: label (or NULL for the current label) + * @cxt: context * @ids: returns allocated array with FDISK_FIELD_* IDs * @nids: returns number of items in fields * @@ -110,7 +111,7 @@ int fdisk_label_require_geometry(const struct fdisk_label *lb) * function. If the details are enabled then this function usually returns more * fields. * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_label_get_fields_ids( const struct fdisk_label *lb, @@ -257,7 +258,7 @@ int fdisk_field_is_number(const struct fdisk_field *field) * * Write in-memory changes to disk. Be careful! * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_write_disklabel(struct fdisk_context *cxt) { @@ -297,7 +298,7 @@ int fdisk_verify_disklabel(struct fdisk_context *cxt) * This function uses libfdisk ASK interface to print data. The details about * partitions table are printed by FDISK_ASKTYPE_INFO. * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_list_disklabel(struct fdisk_context *cxt) { @@ -321,7 +322,7 @@ int fdisk_list_disklabel(struct fdisk_context *cxt) * * The function modifies in-memory data only. * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_create_disklabel(struct fdisk_context *cxt, const char *name) { @@ -391,7 +392,7 @@ int fdisk_locate_disklabel(struct fdisk_context *cxt, int n, const char **name, * @cxt: fdisk context * @id: returns pointer to allocated string (MBR Id or GPT dirk UUID) * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_get_disklabel_id(struct fdisk_context *cxt, char **id) { @@ -408,7 +409,7 @@ int fdisk_get_disklabel_id(struct fdisk_context *cxt, char **id) * fdisk_set_disklabel_id: * @cxt: fdisk context * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_set_disklabel_id(struct fdisk_context *cxt) { @@ -427,7 +428,7 @@ int fdisk_set_disklabel_id(struct fdisk_context *cxt) * @partnum: partition number * @t: new type * - * Returns 0 on success, < 0 on error. + * Returns: 0 on success, < 0 on error. */ int fdisk_set_partition_type(struct fdisk_context *cxt, size_t partnum, @@ -459,9 +460,9 @@ int fdisk_set_partition_type(struct fdisk_context *cxt, * fdisk_toggle_partition_flag: * @cxt: fdisk context * @partnum: partition number - * @status: flags + * @flag: flag ID * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_toggle_partition_flag(struct fdisk_context *cxt, size_t partnum, @@ -486,7 +487,7 @@ int fdisk_toggle_partition_flag(struct fdisk_context *cxt, * * Sort partitions according to the partition start sector. * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_reorder_partitions(struct fdisk_context *cxt) { @@ -540,8 +541,9 @@ int fdisk_label_is_changed(const struct fdisk_label *lb) /** * fdisk_label_set_disabled: * @lb: label + * @disabled: 0 or 1 * - * Mark label as disabled, then libfdisk is going to ignore the label when + * 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) diff --git a/libfdisk/src/libfdisk.h.in b/libfdisk/src/libfdisk.h.in index a7c7d03e6..52b18db26 100644 --- a/libfdisk/src/libfdisk.h.in +++ b/libfdisk/src/libfdisk.h.in @@ -153,7 +153,7 @@ int fdisk_next_label(struct fdisk_context *cxt, struct fdisk_label **lb); size_t fdisk_get_nlabels(struct fdisk_context *cxt); int fdisk_has_label(struct fdisk_context *cxt); -int fdisk_is_labeltype(struct fdisk_context *cxt, enum fdisk_labeltype l); +int fdisk_is_labeltype(struct fdisk_context *cxt, enum fdisk_labeltype id); #define fdisk_is_label(c, x) fdisk_is_labeltype(c, FDISK_DISKLABEL_ ## x) @@ -289,10 +289,10 @@ extern const struct fdisk_field *fdisk_label_get_field_by_name( const struct fdisk_label *lb, const char *name); -extern int fdisk_field_get_id(const struct fdisk_field *fl); -extern const char *fdisk_field_get_name(const struct fdisk_field *fl); -extern double fdisk_field_get_width(const struct fdisk_field *fl); -extern int fdisk_field_is_number(const struct fdisk_field *fl); +extern int fdisk_field_get_id(const struct fdisk_field *field); +extern const char *fdisk_field_get_name(const struct fdisk_field *field); +extern double fdisk_field_get_width(const struct fdisk_field *field); +extern int fdisk_field_is_number(const struct fdisk_field *field); extern void fdisk_label_set_changed(struct fdisk_label *lb, int changed); @@ -500,7 +500,7 @@ int fdisk_script_get_nlines(struct fdisk_script *dp); int fdisk_script_read_context(struct fdisk_script *dp, struct fdisk_context *cxt); int fdisk_script_write_file(struct fdisk_script *dp, FILE *f); int fdisk_script_read_file(struct fdisk_script *dp, FILE *f); -int fdisk_script_read_line(struct fdisk_script *dp, FILE *f, char *buf, size_t sz); +int fdisk_script_read_line(struct fdisk_script *dp, FILE *f, char *buf, size_t bufsz); int fdisk_set_script(struct fdisk_context *cxt, struct fdisk_script *dp); struct fdisk_script *fdisk_get_script(struct fdisk_context *cxt); diff --git a/libfdisk/src/partition.c b/libfdisk/src/partition.c index d823857bf..7d4d57669 100644 --- a/libfdisk/src/partition.c +++ b/libfdisk/src/partition.c @@ -6,8 +6,8 @@ /** * SECTION: partition - * @title: partition abstraction - * @short_description: generic label independent partition + * @title: Partition + * @short_description: generic label independent partition abstraction * * The fdisk_partition provides label independent abstraction. The partitions * are not directly connected with partition table (label) data. Any change to @@ -73,7 +73,7 @@ void fdisk_reset_partition(struct fdisk_partition *pa) /** * fdisk_ref_partition: - * @tb: partition pointer + * @pa: partition pointer * * Incremparts reference counter. */ @@ -301,7 +301,7 @@ int fdisk_partition_size_explicit(struct fdisk_partition *pa, int enable) /** * fdisk_partition_set_partno: * @pa: partition - * @parto: partitin number (0 is the first partition, maximal is SIZE_MAX-1) + * @num: partitin number (0 is the first partition, maximal is SIZE_MAX-1) * * Note that zero is valid partno too. Use fdisk_partition_unset_partno() to * undefine the partno. @@ -594,6 +594,7 @@ int fdisk_partition_next_partno( /** * fdisk_partition_to_string: * @pa: partition + * @cxt: context * @id: field (FDISK_FIELD_*) * @data: returns string with allocated data * @@ -614,7 +615,7 @@ int fdisk_partition_next_partno( * * returns UUID for the first partition. * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_partition_to_string(struct fdisk_partition *pa, struct fdisk_context *cxt, @@ -905,6 +906,7 @@ int fdisk_delete_all_partitions(struct fdisk_context *cxt) /** * fdisk_is_partition_used: + * @cxt: context * @n: partition number (0 is the first partition) * * This is faster than fdisk_get_partition() + fdisk_partition_is_used(). diff --git a/libfdisk/src/parttype.c b/libfdisk/src/parttype.c index 1e39eff10..aedf4e83b 100644 --- a/libfdisk/src/parttype.c +++ b/libfdisk/src/parttype.c @@ -5,7 +5,7 @@ #include "fdiskP.h" /** - * SECTION: parttypw + * SECTION: parttype * @title: Partition types * @short_description: abstraction to partition types * @@ -123,7 +123,7 @@ int fdisk_parttype_set_typestr(struct fdisk_parttype *t, const char *str) /** * fdisk_parttype_set_code: * @t: partition type - * @int: type identificator (e.g. MBR type codes) + * @code: type identificator (e.g. MBR type codes) * * Sets type code to allocated partition type, for static types it returns * -EINVAL. Don't use this function for GPT, see fdisk_parttype_set_typestr(). diff --git a/libfdisk/src/script.c b/libfdisk/src/script.c index 2353cb8a2..83bda995d 100644 --- a/libfdisk/src/script.c +++ b/libfdisk/src/script.c @@ -4,8 +4,8 @@ /** * SECTION: script - * @title: Partition table script - * @short_description: text based description of partition table + * @title: Script + * @short_description: text based sfdisk compatible description of partition table * * The libfdisk scripts are based on original sfdisk script (dumps). Each * script has two parts: script headers and partition table entries @@ -50,6 +50,7 @@ static void fdisk_script_free_header(struct fdisk_script *dp, struct fdisk_scrip /** * fdisk_new_script: + * @cxt: context * * The script hold fdisk_table and additional information to read/write * script to the file. @@ -914,6 +915,8 @@ int fdisk_script_read_buffer(struct fdisk_script *dp, char *s) * fdisk_script_read_line: * @dp: script * @f: file + * @buf: buffer to store one line of the file + * @bufsz: buffer size * * Reads next line into dump. * @@ -960,7 +963,7 @@ int fdisk_script_read_line(struct fdisk_script *dp, FILE *f, char *buf, size_t b /** * fdisk_script_read_file: * @dp: script - * @f input file + * @f: input file * * Reads file @f into script @dp. * @@ -1038,11 +1041,11 @@ struct fdisk_script *fdisk_get_script(struct fdisk_context *cxt) /** * fdisk_apply_script_headers: * @cxt: context - * dp: script + * @dp: script * * Associte context @cxt with script @dp and creates a new empty disklabel. * - * Return: 0 on success, <0 on error. + * Returns: 0 on success, <0 on error. */ int fdisk_apply_script_headers(struct fdisk_context *cxt, struct fdisk_script *dp) { diff --git a/libfdisk/src/sgi.c b/libfdisk/src/sgi.c index b06556976..ce30f3e61 100644 --- a/libfdisk/src/sgi.c +++ b/libfdisk/src/sgi.c @@ -24,8 +24,8 @@ /** * SECTION: sgi - * @title: SGI functions - * @short_description: SGI disk label specific functionality + * @title: SGI + * @short_description: disk label specific functions * */ diff --git a/libfdisk/src/sun.c b/libfdisk/src/sun.c index 04bf0dda1..eb7bb43eb 100644 --- a/libfdisk/src/sun.c +++ b/libfdisk/src/sun.c @@ -23,8 +23,8 @@ /** * SECTION: sun - * @title: SUN functions - * @short_description: SUN disklabel specific functions + * @title: SUN + * @short_description: disk label specific functions * */ diff --git a/libfdisk/src/table.c b/libfdisk/src/table.c index 3a78e9e02..8adbd7f36 100644 --- a/libfdisk/src/table.c +++ b/libfdisk/src/table.c @@ -3,7 +3,7 @@ /** * SECTION: table - * @title: table + * @title: Table * @short_description: container for fdisk partitions * * The fdisk_table is simple container for fdisk_partitions. The table is no @@ -272,7 +272,7 @@ int fdisk_table_remove_partition(struct fdisk_table *tb, struct fdisk_partition * This function adds partitions from disklabel to @table, it allocates a new * table if if @table points to NULL. * - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_get_partitions(struct fdisk_context *cxt, struct fdisk_table **tb) { @@ -319,6 +319,8 @@ static int cmp_parts_wrapper(struct list_head *a, struct list_head *b, void *dat * @cmp: compare function * * Sort partition in the table. + * + * Returns: 0 on success, <0 on error. */ int fdisk_table_sort_partitions(struct fdisk_table *tb, int (*cmp)(struct fdisk_partition *, @@ -475,7 +477,7 @@ done: * * Note that free space smaller than grain (see fdisk_get_grain()) is ignored. - * Returns 0 on success, otherwise, a corresponding error. + * Returns: 0 on success, otherwise, a corresponding error. */ int fdisk_get_freespaces(struct fdisk_context *cxt, struct fdisk_table **tb) { diff --git a/libfdisk/src/utils.c b/libfdisk/src/utils.c index b705f9eb4..482a3062d 100644 --- a/libfdisk/src/utils.c +++ b/libfdisk/src/utils.c @@ -6,7 +6,7 @@ /** * SECTION: utils - * @title: Misc utils + * @title: Utils * @short_description: misc fdisk functions */ @@ -77,7 +77,7 @@ int fdisk_read_firstsector(struct fdisk_context *cxt) /** * fdisk_partname: - * dev: device name + * @dev: device name * @partno: partition name * * Return: allocated buffer with partition name, use free() to deallocate.