From: Karel Zak <kzak@redhat.com>
Date: Mon, 7 Apr 2014 12:07:49 +0000 (+0200)
Subject: libsmartcols: improve docs
X-Git-Tag: v2.25-rc1~297
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e2310281c74bfaae4d3618ddd5d0568c494eda6a;p=thirdparty%2Futil-linux.git

libsmartcols: improve docs

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

diff --git a/libsmartcols/docs/libsmartcols-docs.xml b/libsmartcols/docs/libsmartcols-docs.xml
index a699fd07be..6145ec3089 100644
--- a/libsmartcols/docs/libsmartcols-docs.xml
+++ b/libsmartcols/docs/libsmartcols-docs.xml
@@ -42,6 +42,8 @@ available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
   <part>
     <title>Misc</title>
     <xi:include href="xml/iter.xml"/>
+    <xi:include href="xml/version.xml"/>
+    <xi:include href="xml/init.xml"/>
   </part>
   <index id="api-index-full">
     <title>API Index</title>
diff --git a/libsmartcols/src/cell.c b/libsmartcols/src/cell.c
index 28e2557860..491b8a15c0 100644
--- a/libsmartcols/src/cell.c
+++ b/libsmartcols/src/cell.c
@@ -13,7 +13,9 @@
  * @title: Cell
  * @short_description: cell API
  *
- * An API to access and modify per-cell data and information.
+ * An API to access and modify per-cell data and information. Note that cell is
+ * always part of the line. If you destroy (un-reference) a line than it
+ * destroys all line cells too.
  */
 
 
@@ -146,7 +148,7 @@ int scols_cell_set_color(struct libscols_cell *ce, const char *color)
 }
 
 /**
- * scols_cell_get_data:
+ * scols_cell_get_color:
  * @ce: a pointer to a struct libscols_cell instance
  *
  * Returns: the current color of @ce.
diff --git a/libsmartcols/src/column.c b/libsmartcols/src/column.c
index 91e3655cb9..4ee782fb24 100644
--- a/libsmartcols/src/column.c
+++ b/libsmartcols/src/column.c
@@ -175,7 +175,7 @@ int scols_column_get_flags(struct libscols_column *cl)
 }
 
 /**
- * scols_column_get_flags:
+ * scols_column_get_header:
  * @cl: a pointer to a struct libscols_column instance
  *
  * Returns: A pointer to a struct libscols_cell instance, representing the
diff --git a/libsmartcols/src/init.c b/libsmartcols/src/init.c
index 97e0880594..95b4610b77 100644
--- a/libsmartcols/src/init.c
+++ b/libsmartcols/src/init.c
@@ -9,6 +9,8 @@
  * SECTION: init
  * @title: Library initialization
  * @short_description: initialize debugging
+ *
+ * The library debug stuff.
  */
 
 #include <stdarg.h>
diff --git a/libsmartcols/src/libsmartcols.h.in b/libsmartcols/src/libsmartcols.h.in
index 579a28a7ea..b3ceeeab96 100644
--- a/libsmartcols/src/libsmartcols.h.in
+++ b/libsmartcols/src/libsmartcols.h.in
@@ -18,6 +18,11 @@ extern "C" {
 #include <stdio.h>
 #include <sys/types.h>
 
+/**
+ * LIBSMARTCOLS_VERSION:
+ *
+ * Library version string
+ */
 #define LIBSMARTCOLS_VERSION   "@LIBSMARTCOLS_VERSION@"
 
 /**
diff --git a/libsmartcols/src/line.c b/libsmartcols/src/line.c
index 931cc08218..686a119454 100644
--- a/libsmartcols/src/line.c
+++ b/libsmartcols/src/line.c
@@ -106,7 +106,10 @@ void scols_line_free_cells(struct libscols_line *ln)
  * @ln: a pointer to a struct libscols_line instance
  * @n: the number of elements
  *
- * Allocates space for @n cells.
+ * Allocates space for @n cells. This function is optional,
+ * and libsmartcols automatically allocates necessary cells
+ * according to number of columns in the table when you add
+ * the line to the table. See scols_table_add_line().
  *
  * Returns: 0, a negative value in case of an error.
  */
@@ -369,7 +372,7 @@ int scols_line_set_data(struct libscols_line *ln, size_t n, const char *data)
 }
 
 /**
- * scols_line_set_data:
+ * scols_line_refer_data:
  * @ln: a pointer to a struct libscols_cell instance
  * @n: number of the cell which will refer to @data
  * @data: actual data to refer to
diff --git a/libsmartcols/src/table.c b/libsmartcols/src/table.c
index 1fa7d05f01..914cc2ed9a 100644
--- a/libsmartcols/src/table.c
+++ b/libsmartcols/src/table.c
@@ -9,11 +9,11 @@
  */
 
 /**
- * SECTION: table 
+ * SECTION: table
  * @title: Table
- * @short_description: table API
+ * @short_description: table data API
  *
- * Table manipulation API.
+ * Table data manipulation API.
  */
 
 
@@ -284,7 +284,7 @@ int scols_table_get_ncols(struct libscols_table *tb)
 	return tb ? tb->ncols : -EINVAL;
 }
 
-/*
+/**
  * scols_table_get_nlines:
  * @tb: table
  *
diff --git a/libsmartcols/src/table_print.c b/libsmartcols/src/table_print.c
index 6b846d49db..d25bd252df 100644
--- a/libsmartcols/src/table_print.c
+++ b/libsmartcols/src/table_print.c
@@ -7,6 +7,14 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: table_print
+ * @title: Table print
+ * @short_description: table print API
+ *
+ * Table output API.
+ */
+
 #include <stdlib.h>
 #include <unistd.h>
 #include <string.h>
@@ -534,7 +542,7 @@ static size_t strlen_line(struct libscols_line *ln)
 	return sz;
 }
 
-/*
+/**
  * scols_print_table:
  * @tb: table
  *
@@ -588,7 +596,7 @@ int scols_print_table(struct libscols_table *tb)
 	return 0;
 }
 
-/*
+/**
  * scols_print_table_to_string:
  * @tb: table
  * @data: pointer to the beginning of a memory area to print to