From e2310281c74bfaae4d3618ddd5d0568c494eda6a Mon Sep 17 00:00:00 2001
From: Karel Zak <kzak@redhat.com>
Date: Mon, 7 Apr 2014 14:07:49 +0200
Subject: [PATCH] libsmartcols: improve docs

Signed-off-by: Karel Zak <kzak@redhat.com>
---
 libsmartcols/docs/libsmartcols-docs.xml |  2 ++
 libsmartcols/src/cell.c                 |  6 ++++--
 libsmartcols/src/column.c               |  2 +-
 libsmartcols/src/init.c                 |  2 ++
 libsmartcols/src/libsmartcols.h.in      |  5 +++++
 libsmartcols/src/line.c                 |  7 +++++--
 libsmartcols/src/table.c                |  8 ++++----
 libsmartcols/src/table_print.c          | 12 ++++++++++--
 8 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/libsmartcols/docs/libsmartcols-docs.xml b/libsmartcols/docs/libsmartcols-docs.xml
index a699fd07b..6145ec308 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 28e255786..491b8a15c 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 91e3655cb..4ee782fb2 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 97e088059..95b4610b7 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 579a28a7e..b3ceeeab9 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 931cc0821..686a11945 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 1fa7d05f0..914cc2ed9 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 6b846d49d..d25bd252d 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