libsmartcols: improve docs

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

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>

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.

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

libsmartcols/src/init.c

@@ -9,6 +9,8 @@
  * SECTION: init
  * @title: Library initialization
  * @short_description: initialize debugging
+ *
+ * The library debug stuff.
  */
 
 #include <stdarg.h>

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@"
 
 /**

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

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
  *

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