Merge lp:~gue5t/midori/docs-and-gir-1 into lp:midori

[gue5t gue5t]

Improve docs and GIR annotations for KatzeItem, KatzeArray, and MidoriWebSettings

We'll need a lot more attention to documentation before GIR/libpeas is feasible, but I figured I'd start with infrastructure stuff and work upward.

I've been running build with GtkDoc enabled and also using commands along the lines of "g-ir-scanner -Imidori -I../ -I../midori -I../katze -I../toolbars -I. --header-only -n Midori --identifier-prefix Midori -L./midori/ ../midori/midori-websettings.c ../midori/midori-websettings.h --pkg gtk+-2.0 --pkg webkit-1.0 --pkg gio-2.0 --pkg gobject-2.0 --warn-all -iGObject-2.0 -iGLib-2.0 -iGtk-2.0 -o gir-1.0/MidoriSettings-1.0.gir" to get tooling feedback so far.

[Cris Dywan (kalikiana)]

Can we run the g-ir-scanner as part of the build? Or, if for whatever reason that's not feasible right now as an optional target or command. Otherwise it's somewhat tricky to verify that the annotations work/ continue to work.

That said, look very very nice. I second getting these things solved progressively.

review: Needs Information

[lp:~gue5t/midori/docs-and-gir-1]

6582. By gue5t <email address hidden> on 2014-03-04

Implement GIR build support

[gue5t gue5t (gue5t)]

Ah, this isn't quite right--g-ir-scanner needs to run after midori-core.h has been generated, and probably should be off by default to avoid deps on GIR for packagers.

[lp:~gue5t/midori/docs-and-gir-1]

6583. By gue5t <email address hidden> on 2014-03-04

Turn off GIR xml generation by default, and make it run after compile when enabled

[Cris Dywan (kalikiana)]

Sweet! Thanks a lot!

review: Approve

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2014-03-01 12:00:40 +0000
+++ CMakeLists.txt	2014-03-04 14:42:35 +0000
@@ -159,6 +159,7 @@
 option(USE_ZEITGEIST "Zeitgeist history integration" ON)
 option(USE_GRANITE "Fancy notebook and pop-overs" OFF)
 option(USE_APIDOCS "API documentation" OFF)
+option(USE_GIR "Generate GObject Introspection bindings" OFF)
 option(EXTRA_WARNINGS "Additional compiler warnings" OFF)
 
 # GTK+3 is implied here, whether set or not
@@ -288,3 +289,6 @@
 if (USE_APIDOCS)
     add_subdirectory (docs/api)
 endif ()
+if (USE_GIR)
+    add_subdirectory (gir)
+endif ()

=== added file 'cmake/GIR.cmake'
--- cmake/GIR.cmake	1970-01-01 00:00:00 +0000
+++ cmake/GIR.cmake	2014-03-04 14:42:35 +0000
@@ -0,0 +1,31 @@
+# GIR.cmake
+#
+# Macros for building Gobject Introspection bindings for Midori API
+find_program (GIR_SCANNER_BIN g-ir-scanner)
+find_program (GIR_COMPILER_BIN g-ir-compiler)
+
+if (GIR_SCANNER_BIN AND GIR_COMPILER_BIN)
+
+    set (GIR_FOUND TRUE)
+    set (GIR_VERSION "${MIDORI_MAJOR_VERSION}.${MIDORI_MINOR_VERSION}")
+    macro (gir_build module namespace)
+        add_custom_target ("g-ir-scanner_${module}" ALL
+            ${GIR_SCANNER_BIN} -Imidori -I${CMAKE_SOURCE_DIR}/ -I${CMAKE_BINARY_DIR}/midori -I${CMAKE_SOURCE_DIR}/${module} -I${CMAKE_SOURCE_DIR}/toolbars -I.
+                --header-only -n ${namespace} --identifier-prefix ${namespace}
+                ${CMAKE_SOURCE_DIR}/${module}/${module}-*.c ${CMAKE_SOURCE_DIR}/${module}/${module}-*.h
+                --pkg gtk+-2.0 --pkg webkit-1.0 --pkg gio-2.0 --pkg gobject-2.0
+                --warn-all -iGObject-2.0 -iGLib-2.0 -iGtk-2.0
+                --nsversion ${GIR_VERSION}
+                -o ${CMAKE_CURRENT_BINARY_DIR}/${namespace}-${GIR_VERSION}.gir
+                WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+                DEPENDS ${CMAKE_PROJECT_NAME})
+
+    endmacro (gir_build module namespace)
+
+    macro (gir module namespace)
+        gir_build (${module} ${namespace})
+
+        install (FILES "${CMAKE_CURRENT_BINARY_DIR}/${namespace}-${GIR_VERSION}.gir"
+            DESTINATION "${CMAKE_INSTALL_DATADIR}/gir-1.0/")
+    endmacro (gir module)
+endif ()

=== added directory 'gir'
=== added file 'gir/CMakeLists.txt'
--- gir/CMakeLists.txt	1970-01-01 00:00:00 +0000
+++ gir/CMakeLists.txt	2014-03-04 14:42:35 +0000
@@ -0,0 +1,15 @@
+# Copyright (C) 2013 Olivier Duchateau
+
+include (GIR)
+
+if (GIR_FOUND)
+    list (APPEND MODULES "Katze" "Midori")
+    foreach (MOD ${MODULES})
+        string(TOLOWER ${MOD} LOWER_MOD)
+        if (EXISTS "${CMAKE_SOURCE_DIR}/${LOWER_MOD}")
+            gir (${LOWER_MOD} ${MOD})
+        endif ()
+    endforeach ()
+else ()
+    message (FATAL_ERROR "g-ir-scanner not found")
+endif ()

=== modified file 'katze/katze-array.c'
--- katze/katze-array.c	2013-11-04 20:57:37 +0000
+++ katze/katze-array.c	2014-03-04 14:42:35 +0000
@@ -229,7 +229,7 @@
  * The array will keep a reference on each object until
  * it is removed from the array.
  *
- * Return value: a new #KatzeArray
+ * Return value: (transfer full): a new #KatzeArray
  **/
 KatzeArray*
 katze_array_new (GType type)
@@ -252,7 +252,7 @@
  * Checks whether the array is compatible
  * with items of the specified type.
  *
- * Retur value: %TRUE if @array is compatible with @is_a_type
+ * Return value: %TRUE if @array is compatible with @is_a_type
  **/
 gboolean
 katze_array_is_a (KatzeArray* array,
@@ -266,7 +266,7 @@
 /**
  * katze_array_add_item:
  * @array: a #KatzeArray
- * @item: an item
+ * @item: (type GObject) (transfer none): an item
  *
  * Adds an item to the array.
  *
@@ -284,7 +284,7 @@
 /**
  * katze_array_remove_item:
  * @array: a #KatzeArray
- * @item: an item
+ * @item: (type GObject): an item
  *
  * Removes an item from the array.
  *
@@ -306,7 +306,7 @@
  *
  * Retrieves the item in @array at the position @n.
  *
- * Return value: an item, or %NULL
+ * Return value: (type GObject) (transfer none): an item, or %NULL
  **/
 gpointer
 katze_array_get_nth_item (KatzeArray* array,
@@ -323,7 +323,7 @@
  *
  * Determines whether @array is empty.
  *
- * Return value: an item, or %NULL
+ * Return value: %TRUE if the array is empty
  **/
 gboolean
 katze_array_is_empty (KatzeArray* array)
@@ -336,11 +336,12 @@
 /**
  * katze_array_get_item_index:
  * @array: a #KatzeArray
- * @item: an item in the array
+ * @item: (type GObject): an item in the array
  *
  * Retrieves the index of the item in @array.
  *
- * Return value: an item, or -1
+ * Return value: the index of the item, or -1 if the item is not
+ * present in the array
  **/
 gint
 katze_array_get_item_index (KatzeArray* array,
@@ -358,14 +359,14 @@
  *
  * Looks up an item in the array which has the specified token.
  *
- * This function will fail if the type of the list
- * is not based on #KatzeItem children.
+ * This function will fail and return NULL if the #KatzeArray's
+ * element type is not based on #KatzeItem.
  *
  * Note that @token is by definition unique to one item.
  *
  * Since 0.4.4 @token can be a "token keywords" string.
  *
- * Return value: an item, or %NULL
+ * Return value: (type GObject) (transfer none): an item, or %NULL
  **/
 gpointer
 katze_array_find_token (KatzeArray*  array,
@@ -403,10 +404,10 @@
  *
  * Looks up an item in the array which has the specified URI.
  *
- * This function will fail if the type of the list
- * is not based on #KatzeItem children.
+ * This function will fail and return NULL if the #KatzeArray's
+ * element type is not based on #KatzeItem.
  *
- * Return value: an item, or %NULL
+ * Return value: (type GObject) (transfer none): an item, or %NULL
  *
  * Since: 0.2.0
  **/
@@ -435,7 +436,7 @@
  *
  * Retrieves the number of items in @array.
  *
- * Return value: the length of the list
+ * Return value: the length of the #KatzeArray
  **/
 guint
 katze_array_get_length (KatzeArray* array)
@@ -448,7 +449,7 @@
 /**
  * katze_array_move_item:
  * @array: a #KatzeArray
- * @item: the item being moved
+ * @item: (type GObject): the item being moved
  * @position: the new position of the item
  *
  * Moves @item to the position @position.
@@ -471,7 +472,7 @@
  *
  * Retrieves the items as a list.
  *
- * Return value: a newly allocated #GList of items
+ * Return value: (element-type GObject) (transfer container): a newly allocated #GList of items
  *
  * Since: 0.2.5
  **/
@@ -483,6 +484,14 @@
     return g_list_copy (array->priv->items);
 }
 
+/**
+ * katze_array_peek_items:
+ * @array: a #KatzeArray
+ *
+ * Peeks at the KatzeArray's internal list of items.
+ *
+ * Return value: (element-type GObject) (transfer none): the #KatzeArray's internal #GList of items
+ **/
 GList*
 katze_array_peek_items (KatzeArray* array)
 {

=== modified file 'katze/katze-item.c'
--- katze/katze-item.c	2013-08-05 19:52:52 +0000
+++ katze/katze-item.c	2014-03-04 14:42:35 +0000
@@ -342,7 +342,7 @@
 /**
  * katze_item_set_text:
  * @item: a #KatzeItem
- * @description: a string
+ * @text: a string
  *
  * Sets the descriptive text of @item.
  **/
@@ -435,9 +435,9 @@
  * @item: a #KatzeItem
  * @widget: a #GtkWidget, or %NULL
  *
- * Retrieves a #GdkPixbuf fit to display @item.
+ * Creates a #GdkPixbuf fit to display @item.
  *
- * Return value: the icon of the item
+ * Return value: (transfer full): the icon of the item, or %NULL
  *
  * Since: 0.4.6
  **/
@@ -495,12 +495,12 @@
  * @item: a #KatzeItem
  * @widget: a #GtkWidget, or %NULL
  *
- * Retrieves a #GtkImage fit to display @item.
+ * Creates a #GtkImage fit to display @item.
  *
- * Return value: the icon of the item
+ * Return value: (transfer floating): the icon of the item
  *
  * Since: 0.4.4
- * Since 0.4.8 a @widget was added and the image is visible.
+ * Since 0.4.8 a @widget was added and the image is set visible.
  **/
 GtkWidget*
 katze_item_get_image (KatzeItem* item,
@@ -600,7 +600,7 @@
  *
  * Retrieves a list of all meta keys.
  *
- * Return value: a newly allocated #GList of constant strings
+ * Return value: (element-type utf8) (transfer container): a newly allocated #GList of constant strings
  *
  * Since: 0.1.8
  **/
@@ -778,7 +778,7 @@
  *
  * Since 0.1.2 you can monitor the "parent" property.
  *
- * Return value: the parent of the item
+ * Return value: (type GObject) (transfer none): the parent of the item
  **/
 gpointer
 katze_item_get_parent (KatzeItem* item)

=== modified file 'midori/midori-websettings.c'
--- midori/midori-websettings.c	2014-02-24 11:33:50 +0000
+++ midori/midori-websettings.c	2014-03-04 14:42:35 +0000
@@ -257,6 +257,13 @@
                                   GValue*     value,
                                   GParamSpec* pspec);
 
+/**
+ * midori_web_settings_low_memory_profile:
+ *
+ * Determines if the system has a relatively small amount of memory.
+ *
+ * Returns: %TRUE if there is relatively little memory available
+ **/
 static gboolean
 midori_web_settings_low_memory_profile ()
 {
@@ -482,7 +489,7 @@
                                      flags));
 
     /**
-     * MidoriWebSettings:enforc-font-family:
+     * MidoriWebSettings:enforce-font-family:
      *
      * Whether to enforce user font preferences with an internal stylesheet.
      *
@@ -611,8 +618,11 @@
 
 /**
  * midori_web_settings_skip_plugin:
+ * @path: the path to the plugin file
  *
- * Tests if a plugin is redundant
+ * Tests if a plugin is redundant. WebKit sometimes provides
+ * duplicate listings of plugins due to library deployment
+ * miscellanea.
  *
  * Returns: %TRUE if the passed plugin shouldn't be shown in UI listings.
  *
@@ -655,6 +665,8 @@
 
 /**
  * midori_web_settings_get_site_data_policy:
+ * @settings: the MidoriWebSettings instance
+ * @uri: the URI for which to make the policy decision
  *
  * Tests if @uri may store site data.
  *
@@ -734,11 +746,11 @@
 
 /**
  * midori_web_settings_get_system_name:
- * @architecture: location of a string, or %NULL
- * @platform: location of a string, or %NULL
+ * @architecture: (out) (allow-none): location of a string, or %NULL
+ * @platform: (out) (allow-none): location of a string, or %NULL
  *
  * Determines the system name, architecture and platform.
- * @architecturce can have a %NULL value.
+ * This function may write a %NULL value to @architecture.
  *
  * Returns: a string
  *
@@ -948,6 +960,13 @@
         katze_assign (settings->accept, g_strdup (languages));
 }
 
+/**
+ * midori_web_settings_get_accept_language:
+ *
+ * Returns the value of the accept-language header to send to web servers
+ *
+ * Returns: the accept-language string
+ **/
 const gchar*
 midori_web_settings_get_accept_language (MidoriWebSettings* settings)
 {
@@ -1080,9 +1099,9 @@
                                                           "default-font-family");
             gchar* monospace = katze_object_get_string (web_settings,
                                                         "monospace-font-family");
-            gchar* css = g_strdup_printf ("body * { font-family: %s !important; } \
-                code, code *, pre, pre *, blockquote, blockquote *, \
-                input, textarea { font-family: %s !important; }",
+            gchar* css = g_strdup_printf ("body * { font-family: %s !important; } "
+                "code, code *, pre, pre *, blockquote, blockquote *, "
+                "input, textarea { font-family: %s !important; }",
                                           font_family, monospace);
             midori_web_settings_add_style (web_settings, "enforce-font-family", css);
             g_free (font_family);
@@ -1250,9 +1269,10 @@
  *
  * Creates a new #MidoriWebSettings instance with default values.
  *
- * You will typically want to assign this to a #MidoriWebView or #MidoriBrowser.
+ * You will typically want to assign this to a #MidoriWebView
+ * or #MidoriBrowser.
  *
- * Return value: a new #MidoriWebSettings
+ * Return value: (transfer full): a new #MidoriWebSettings
  **/
 MidoriWebSettings*
 midori_web_settings_new (void)
@@ -1318,6 +1338,7 @@
 
 /**
  * midori_web_settings_add_style:
+ * @settings: the MidoriWebSettings instance to modify
  * @rule_id: a static string identifier
  * @style: a CSS stylesheet
  *
@@ -1352,6 +1373,7 @@
 
 /**
  * midori_web_settings_remove_style:
+ * @settings: the MidoriWebSettings instance to modify
  * @rule_id: the string identifier used previously
  *
  * Removes a stylesheet from midori settings.
@@ -1378,6 +1400,21 @@
     }
 }
 
+/**
+ * midori_settings_new_full:
+ * @extensions: (out) (allow-none): a pointer into which
+ * to write an array of names of extensions which preferences
+ * indicate should be activated, or %NULL.
+ *
+ * Creates a new #MidoriWebSettings instance, loading
+ * configuration from disk according to preferences and
+ * invocation mode.
+ *
+ * You will typically want to assign this to a #MidoriWebView
+ * or #MidoriBrowser.
+ *
+ * Return value: (transfer full): a new #MidoriWebSettings
+ **/
 MidoriWebSettings*
 midori_settings_new_full (gchar*** extensions)
 {
@@ -1485,6 +1522,20 @@
     return settings;
 }
 
+/**
+ * midori_settings_save_to_file:
+ * @settings: a MidoriWebSettings instance to save
+ * @app: (type Midori.Application) (allow-none): a MidoriApplication instance
+ * @filename: the filename into which to save settings
+ * @error: (out) (allow-none): return location for a GError, or %NULL
+ *
+ * Saves a #MidoriWebSettings instance to disk at the path given by @filename.
+ *
+ * Also saves the list of activated extensions from @app.
+ *
+ * Return value: %TRUE if no error occurred; %FALSE if an error 
+ * occurred, in which case @error will contain detailed information
+ **/
 gboolean
 midori_settings_save_to_file (MidoriWebSettings* settings,
                               GObject*           app,
@@ -1621,4 +1672,3 @@
     g_key_file_free (key_file);
     return saved;
 }
-