Add documentation and annotations

4 files changed, 235 insertions, 11 deletions

diff --git a/libmsi/libmsi-database.c b/libmsi/libmsi-database.c
index 8120b4d..66fa04d 100644
--- a/libmsi/libmsi-database.c
+++ b/libmsi/libmsi-database.c
@@ -1186,6 +1186,16 @@ done:
     return r;
 }
 
+/**
+ * libmsi_database_import:
+ * @db: a %LibmsiDatabase
+ * @path: path to a table file
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Import a table to the database from file @path.
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_database_import (LibmsiDatabase *db,
                         const char *path,
@@ -1312,11 +1322,14 @@ done:
     return r;
 }
 
-/***********************************************************************
- * MsiExportDatabase        [MSI.@]
+/**
+ * libmsi_database_export:
+ * @db: a %LibmsiDatabase
+ * @table: a table name
+ * @fd: a file descriptor
+ * @error: (allow-none): #GError to set on error, or %NULL
  *
  * Writes a file containing the table data as tab separated ASCII.
- *
  * The format is as follows:
  *
  * row1 : colname1 <tab> colname2 <tab> .... colnameN <cr> <lf>
@@ -1326,7 +1339,9 @@ done:
  * Followed by the data, starting at row 1 with one row per line
  *
  * row4 : data <tab> data <tab> data <tab> ... data <cr> <lf>
- */
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_database_export (LibmsiDatabase *db,
                         const char *table,
@@ -1960,6 +1975,15 @@ static unsigned update_merge_errors(LibmsiDatabase *db, const char *error,
     return r;
 }
 
+/**
+ * libmsi_database_merge:
+ * @db: a %LibmsiDatabase to merge into
+ * @merge: a %LibmsiDatabase to merge
+ * @table: (allow-none): an optionnal table name
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_database_merge (LibmsiDatabase *db,
                        LibmsiDatabase *merge,
@@ -2023,6 +2047,12 @@ done:
     return r == LIBMSI_RESULT_SUCCESS;
 }
 
+/**
+ * libmsi_database_is_readonly:
+ * @db: a %LibmsiDatabase
+ *
+ * Returns: %TRUE if the database is read-only.
+ **/
 gboolean
 libmsi_database_is_readonly (LibmsiDatabase *db)
 {
@@ -2175,6 +2205,16 @@ end:
     return ret;
 }
 
+/**
+ * libmsi_database_apply_transform:
+ * @db: a %LibmsiDatabase
+ * @file: an MST transform file path
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * FIXME
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_database_apply_transform (LibmsiDatabase *db,
                                  const char *szTransformFile,
@@ -2270,6 +2310,13 @@ end:
     return ret;
 }
 
+/**
+ * libmsi_database_commit:
+ * @db: a #LibmsiDatabase
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: %TRUE on success.
+ **/
 gboolean
 libmsi_database_commit (LibmsiDatabase *db, GError **error)
 {
@@ -2399,6 +2446,15 @@ unsigned _libmsi_database_get_primary_keys( LibmsiDatabase *db,
     return r;
 }
 
+/**
+ * libmsi_database_get_primary_keys:
+ * @db: a %LibmsiDatabase
+ * @table: an exisiting table name
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: (transfer full): a %LibmsiRecord containing the names of all the primary
+ * key columns.
+ **/
 LibmsiRecord *
 libmsi_database_get_primary_keys (LibmsiDatabase *db,
                                   const char *table,
@@ -2422,6 +2478,14 @@ libmsi_database_get_primary_keys (LibmsiDatabase *db,
     return rec;
 }
 
+/**
+ * libmsi_database_is_table_persistent:
+ * @db: a %LibmsiDatabase
+ * @table: an exisiting table name
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: %TRUE if the @table is persistent, %FALSE if it's temporary
+ **/
 gboolean
 libmsi_database_is_table_persistent (LibmsiDatabase *db, const char *table,
                                      GError **error)
@@ -2471,6 +2535,16 @@ init (LibmsiDatabase *self, GError **error)
     return !ret;
 }
 
+/**
+ * libmsi_database_new:
+ * @path: path to a MSI file
+ * @persist: path to a MSI file or LIBMSI_DB_OPEN flag
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Create a MSI database or open from @path.
+ *
+ * Returns: a new #LibmsiDatabase on success, %NULL if fail.
+ **/
 LibmsiDatabase *
 libmsi_database_new (const gchar *path, const char *persist, GError **error)
 {
diff --git a/libmsi/libmsi-query.c b/libmsi/libmsi-query.c
index 4952d32..1a951c9 100644
--- a/libmsi/libmsi-query.c
+++ b/libmsi/libmsi-query.c
@@ -396,6 +396,17 @@ LibmsiResult _libmsi_query_fetch(LibmsiQuery *query, LibmsiRecord **prec)
     return r;
 }
 
+/**
+ * libmsi_query_fetch:
+ * @query: a #LibmsiQuery
+ * @error: (allow-none): return location for the error
+ *
+ * Return the next query result. A %LIBMSI_RESULT_NO_MORE_ITEMS error
+ * is returned when the query result set has reached the end.
+ *
+ * Returns: (transfer full): a newly allocated #LibmsiRecord
+ *     or %NULL when no results or failure.
+ **/
 LibmsiRecord *
 libmsi_query_fetch (LibmsiQuery *query, GError **error)
 {
@@ -417,6 +428,15 @@ libmsi_query_fetch (LibmsiQuery *query, GError **error)
     return record;
 }
 
+/**
+ * libmsi_query_close:
+ * @query: a #LibmsiQuery
+ * @error: (allow-none): return location for the error
+ *
+ * Release the current result set.
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_query_close (LibmsiQuery *query, GError **error)
 {
@@ -461,6 +481,17 @@ LibmsiResult _libmsi_query_execute(LibmsiQuery *query, LibmsiRecord *rec )
     return view->ops->execute( view, rec );
 }
 
+/**
+ * libmsi_query_execute:
+ * @query: a #LibmsiQuery
+ * @rec: (allow-none): a #LibmsiRecord containing query arguments, or
+ *     %NULL if no arguments needed
+ * @error: (allow-none): return location for the error
+ *
+ * Execute the @query with the arguments from @rec.
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_query_execute (LibmsiQuery *query, LibmsiRecord *rec, GError **error)
 {
@@ -564,6 +595,17 @@ LibmsiResult _libmsi_query_get_column_info( LibmsiQuery *query, LibmsiColInfo in
     return LIBMSI_RESULT_SUCCESS;
 }
 
+/**
+ * libmsi_query_get_column_info:
+ * @query: a #LibmsiQuery
+ * @info: a #LibmsiColInfo specifying the type of information to return
+ * @error: (allow-none): return location for the error
+ *
+ * Get column informations, returned as record string fields.
+ *
+ * Returns: (transfer full): a newly allocated #LibmsiRecord
+ * containing informations or %NULL on error.
+ **/
 LibmsiRecord *
 libmsi_query_get_column_info (LibmsiQuery *query, LibmsiColInfo info, GError **error)
 {
@@ -588,6 +630,14 @@ libmsi_query_get_column_info (LibmsiQuery *query, LibmsiColInfo info, GError **e
     return rec;
 }
 
+/**
+ * libmsi_query_get_error:
+ * @query: a #LibmsiQuery
+ * @column: (out) (allow-none): location to store the allocated column name
+ * @error: (allow-none): return location for the error
+ *
+ * Call this to get more information on the last query error.
+ **/
 void
 libmsi_query_get_error (LibmsiQuery *query, gchar **column, GError **error)
 {
@@ -605,7 +655,17 @@ libmsi_query_get_error (LibmsiQuery *query, gchar **column, GError **error)
     }
 }
 
-LibmsiQuery*
+/**
+ * libmsi_query_new:
+ * @database: a #LibmsiDatabase
+ * @query: a SQL query
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Create a SQL query for @database.
+ *
+ * Returns: a new %LibmsiQuery on success, %NULL on failure
+ **/
+LibmsiQuery *
 libmsi_query_new (LibmsiDatabase *database, const char *query, GError **error)
 {
     LibmsiQuery *self;
diff --git a/libmsi/libmsi-record.c b/libmsi/libmsi-record.c
index d451f20..aa77ad6 100644
--- a/libmsi/libmsi-record.c
+++ b/libmsi/libmsi-record.c
@@ -553,11 +553,11 @@ unsigned _libmsi_record_load_stream_from_file(LibmsiRecord *rec, unsigned field,
 
 /**
  * libmsi_record_load_stream:
- * @record: a %LibmsiRecord
+ * @record: a #LibmsiRecord
  * @field: a field identifier
  * @filename: a filename or %NULL
  *
- * Load the file content as a stream in %field.
+ * Load the file content as a stream in @field.
  *
  * Returns: %TRUE on success.
  **/
@@ -628,7 +628,7 @@ unsigned _libmsi_record_save_stream(const LibmsiRecord *rec, unsigned field, cha
 
 /**
  * libmsi_record_save_stream:
- * @record: a %LibmsiRecord
+ * @rec: a %LibmsiRecord
  * @field: a field identifier
  * @buf: a buffer of size specified by %sz, or %NULL to return size
  * @sz: a pointer to %buf size
diff --git a/libmsi/libmsi-summary-info.c b/libmsi/libmsi-summary-info.c
index a185055..01410a0 100644
--- a/libmsi/libmsi-summary-info.c
+++ b/libmsi/libmsi-summary-info.c
@@ -194,6 +194,12 @@ static unsigned get_property_count( const LibmsiOLEVariant *property )
     return n;
 }
 
+/**
+ * libmsi_summary_info_get_properties:
+ * @si: a #LibmsiSummaryInfo
+ *
+ * Returns: (array) (element-type LibmsiProperty) (transfer full): a new #GArray with the list of set properties
+ **/
 GArray *
 libmsi_summary_info_get_properties (LibmsiSummaryInfo *self)
 {
@@ -557,6 +563,14 @@ static unsigned suminfo_persist( LibmsiSummaryInfo *si )
     return r;
 }
 
+/**
+ * libmsi_summary_info_get_property_type:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to get
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: the property type associated for @prop.
+ **/
 LibmsiPropertyType
 libmsi_summary_info_get_property_type (LibmsiSummaryInfo *self,
                                        LibmsiProperty prop,
@@ -649,6 +663,14 @@ static void _summary_info_get_property (LibmsiSummaryInfo *si, unsigned uiProper
     g_object_unref (si);
 }
 
+/**
+ * libmsi_summary_info_get_int:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to get
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: the property value or -1 on failure
+ **/
 gint
 libmsi_summary_info_get_int (LibmsiSummaryInfo *self, LibmsiProperty prop,
                              GError **error)
@@ -666,6 +688,14 @@ libmsi_summary_info_get_int (LibmsiSummaryInfo *self, LibmsiProperty prop,
     return val;
 }
 
+/**
+ * libmsi_summary_info_get_filetime:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to get
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: the property value or 0 on failure
+ **/
 guint64
 libmsi_summary_info_get_filetime (LibmsiSummaryInfo *self, LibmsiProperty prop,
                                   GError **error)
@@ -683,6 +713,14 @@ libmsi_summary_info_get_filetime (LibmsiSummaryInfo *self, LibmsiProperty prop,
     return val;
 }
 
+/**
+ * libmsi_summary_info_get_string:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to get
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: the property value or %NULL on failure
+ **/
 const gchar *
 libmsi_summary_info_get_string (LibmsiSummaryInfo *self, LibmsiProperty prop,
                                 GError **error)
@@ -755,6 +793,17 @@ end:
     return ret;
 }
 
+/**
+ * libmsi_summary_info_set_string:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to set
+ * @value: a string value
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Set string property @prop.
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_summary_info_set_string (LibmsiSummaryInfo *self, LibmsiProperty prop,
                                 const gchar *value, GError **error)
@@ -778,6 +827,17 @@ libmsi_summary_info_set_string (LibmsiSummaryInfo *self, LibmsiProperty prop,
     return TRUE;
 }
 
+/**
+ * libmsi_summary_info_set_int:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to set
+ * @value: a value
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Set integer property @prop.
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_summary_info_set_int (LibmsiSummaryInfo *self, LibmsiProperty prop,
                              gint value, GError **error)
@@ -803,6 +863,17 @@ libmsi_summary_info_set_int (LibmsiSummaryInfo *self, LibmsiProperty prop,
     return TRUE;
 }
 
+/**
+ * libmsi_summary_info_set_filetime:
+ * @si: a #LibmsiSummaryInfo
+ * @prop: a #LibmsiProperty to set
+ * @value: a value
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Set file time property @prop.
+ *
+ * Returns: %TRUE on success
+ **/
 gboolean
 libmsi_summary_info_set_filetime (LibmsiSummaryInfo *self, LibmsiProperty prop,
                                   guint64 value, GError **error)
@@ -911,7 +982,17 @@ end:
     return r;
 }
 
-gboolean libmsi_summary_info_persist (LibmsiSummaryInfo *si, GError **error)
+/**
+ * libmsi_summary_info_persist:
+ * @si: a #LibmsiSummaryInfo
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Save summary informations.
+ *
+ * Returns: %TRUE on success
+ **/
+gboolean
+libmsi_summary_info_persist (LibmsiSummaryInfo *si, GError **error)
 {
     unsigned ret;
 
@@ -932,8 +1013,17 @@ gboolean libmsi_summary_info_persist (LibmsiSummaryInfo *si, GError **error)
     return ret == LIBMSI_RESULT_SUCCESS;
 }
 
-LibmsiSummaryInfo*
-libmsi_summary_info_new (LibmsiDatabase *database, unsigned update_count, GError **error)
+/**
+ * libmsi_summary_info_new:
+ * @database: a #LibmsiDatabase
+ * @update_count: number of changes allowed
+ * @error: (allow-none): #GError to set on error, or %NULL
+ *
+ * Returns: a #LibmsiSummaryInfo or %NULL on failure
+ **/
+LibmsiSummaryInfo *
+libmsi_summary_info_new (LibmsiDatabase *database, unsigned update_count,
+                         GError **error)
 {
     LibmsiSummaryInfo *self;