Merge lp:~midori/midori/valaDocs into lp:midori

[Cris Dywan]

Replace gtk-doc with valadoc

TODO:
 - cross-link valadoc.org
 - comments from genuine .c files aren't included

[lp:~midori/midori/valaDocs]

6574. By Cris Dywan on 2014-02-28

Fix relation between vapi's and namespaces

Unmerged revisions

6574. By Cris Dywan on 2014-02-28

Fix relation between vapi's and namespaces

6573. By Cris Dywan on 2014-02-27

Replace gtk-doc with valadoc

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2014-02-25 23:30:51 +0000
+++ CMakeLists.txt	2014-02-28 21:47:46 +0000
@@ -26,10 +26,14 @@
                 OUTPUT_VARIABLE REVISION
                 ERROR_QUIET
                 OUTPUT_STRIP_TRAILING_WHITESPACE)
+set(VALACFLAGS
+    --enable-deprecated
+    --debug
+    )
 if (REVISION)
     set(VERSION "${VERSION}~r${REVISION}")
     # All warnings are errors in development builds
-    set(VALAFLAGS ${VALAFLAGS} --fatal-warnings)
+    set(VALACFLAGS ${VALACFLAGS} --fatal-warnings)
     set(CFLAGS "${CFLAGS}")
 endif ()
 add_definitions("-DPACKAGE_VERSION=\"${VERSION}\"")
@@ -40,10 +44,6 @@
 
 find_package(Vala REQUIRED)
 vala_require("0.16.0")
-set(VALAFLAGS ${VALAFLAGS}
-    --enable-deprecated
-    --debug
-    )
 
 include(GNUInstallDirs)
 set(DATADIR ${CMAKE_INSTALL_FULL_DATADIR})
@@ -237,6 +237,8 @@
     set(PKGS ${PKGS} gtk+-2.0)
     set(EXTRA_VAPIS ${EXTRA_VAPIS} "${CMAKE_SOURCE_DIR}/midori/webkitgtk-3.0.vapi")
 endif ()
+set(EXTRA_VAPIS ${EXTRA_VAPIS} "${CMAKE_SOURCE_DIR}/katze/katze.vapi")
+set(EXTRA_VAPIS ${EXTRA_VAPIS} "${CMAKE_SOURCE_DIR}/midori/sokoke.vapi")
 
 # dh_translations detects this if there's no variable used
 set (GETTEXT_PACKAGE "midori")
@@ -268,6 +270,8 @@
 # Explicitly add -fPIC for older toolchains
 set(VALA_CFLAGS "-w -g -fPIC")
 
+set(VALACFLAGS ${VALACFLAGS} ${VALAFLAGS})
+
 set(LIBMIDORI "${CMAKE_PROJECT_NAME}-core")
 
 # CMake provides no uninstall target by design
@@ -284,7 +288,4 @@
 add_subdirectory (icons)
 add_subdirectory (data)
 add_subdirectory (config)
-
-if (USE_APIDOCS)
-    add_subdirectory (docs/api)
-endif ()
+add_subdirectory (docs)
 
=== added file 'docs/CMakeLists.txt'
--- docs/CMakeLists.txt	1970-01-01 00:00:00 +0000
+++ docs/CMakeLists.txt	2014-02-28 21:47:46 +0000
@@ -0,0 +1,51 @@
+# Copyright (C) 2014 Christian Dywan <[e-mail]>
+
+# Serialize deps packages for valadoc
+foreach(pkg ${PKGS})
+    list(APPEND VALADOC_PKG_OPTS "--pkg=${pkg}")
+endforeach()
+
+# Source files to scan
+file(GLOB SRC_FILES
+    ${CMAKE_SOURCE_DIR}/katze/*.c
+    ${CMAKE_SOURCE_DIR}/midori/*.c
+    ${CMAKE_SOURCE_DIR}/katze/*.vala
+    ${CMAKE_SOURCE_DIR}/midori/*.vala
+    ${EXTRA_VAPIS}
+    ${CMAKE_SOURCE_DIR}/midori/midori.vapi
+    )
+
+set(BASE_VALADOC_COMMAND
+   valadoc
+   ${VALAFLAGS}
+   ${VALADOC_PKG_OPTS}
+   ${SRC_FILES}
+   --target-glib=2.32.3
+   --package-name=${CMAKE_PROJECT_NAME}
+   --package-version=${VERSION})
+
+# C API Documentation
+
+add_custom_target(cdocs)
+set(C_API_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/api/c")
+add_custom_command(TARGET cdocs
+    DEPENDS ${LIBMIDORI}
+    COMMAND rm ${C_API_DOC_DIR} -R -f # delete previous files
+    COMMAND ${BASE_VALADOC_COMMAND} ${VALADOC_PKG_OPTS} -o ${C_API_DOC_DIR}
+    --doclet-arg=${CMAKE_BINARY_DIR}/midori/${LIBMIDORI}.h --doclet=gtkdoc
+    )
+
+# Vala API documentation
+
+add_custom_target(valadocs)
+set(VALA_API_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/api/vala")
+add_custom_command(TARGET valadocs
+    COMMAND rm ${VALA_API_DOC_DIR} -R -f # delete previous files
+    COMMAND ${BASE_VALADOC_COMMAND} --doclet=html -o ${VALA_API_DOC_DIR}
+    )
+
+# All the documents
+if (USE_APIDOCS)
+    set(DOCS_IN_ALL "ALL")
+endif ()
+add_custom_target(docs ${DOCS_IN_ALL} DEPENDS cdocs valadocs)
 
=== removed file 'docs/api/CMakeLists.txt'
--- docs/api/CMakeLists.txt	2013-09-26 21:57:12 +0000
+++ docs/api/CMakeLists.txt	1970-01-01 00:00:00 +0000
@@ -1,14 +0,0 @@
-# Copyright (C) 2013 Olivier Duchateau
-
-include (GtkDoc)
-
-if (GTKDOC_FOUND)
-    list (APPEND MODULES "katze" "midori")
-    foreach (MOD ${MODULES})
-        if (EXISTS "${CMAKE_SOURCE_DIR}/${MOD}")
-            gtkdoc (${MOD})
-        endif ()
-    endforeach ()
-else ()
-    message (FATAL_ERROR "gtk-doc not found")
-endif ()
 
=== modified file 'extensions/CMakeLists.txt'
--- extensions/CMakeLists.txt	2014-02-12 20:29:54 +0000
+++ extensions/CMakeLists.txt	2014-02-28 21:47:46 +0000
@@ -53,11 +53,13 @@
             PACKAGES
                 ${PKGS}
             OPTIONS
-                ${VALAFLAGS}
+                ${VALACFLAGS}
+                --use-header="${CMAKE_PROJECT_NAME}-core.h"
+            GENERATE_HEADER
+                "${UNIT_SRC}"
             CUSTOM_VAPIS
                 ${EXTRA_VAPIS}
                 "${CMAKE_SOURCE_DIR}/midori/midori.vapi"
-                "${CMAKE_SOURCE_DIR}/katze/katze.vapi"
                 "${CMAKE_BINARY_DIR}/midori/${LIBMIDORI}.vapi"
             )
             set(UNIT_FILES ${UNIT_FILES} ${UNIT_SRC_C})
@@ -87,11 +89,13 @@
         PACKAGES
             ${PKGS}
         OPTIONS
-            ${VALAFLAGS}
+            ${VALACFLAGS}
+            --use-header="${CMAKE_PROJECT_NAME}-core.h"
+        GENERATE_HEADER
+            "${UNIT}"
         CUSTOM_VAPIS
             ${EXTRA_VAPIS}
             "${CMAKE_SOURCE_DIR}/midori/midori.vapi"
-            "${CMAKE_SOURCE_DIR}/katze/katze.vapi"
             "${CMAKE_BINARY_DIR}/midori/${LIBMIDORI}.vapi"
         )
         add_library(${UNIT} MODULE ${UNIT_SRC_C})
 
=== modified file 'extensions/apps.vala'
--- extensions/apps.vala	2014-01-25 21:34:30 +0000
+++ extensions/apps.vala	2014-02-28 21:47:46 +0000
@@ -9,6 +9,8 @@
    See the file COPYING for the full license text.
 */
 
+extern const string PACKAGE_NAME;
+
 namespace Apps {
     const string APP_PREFIX = PACKAGE_NAME + " -a ";
     const string PROFILE_PREFIX = PACKAGE_NAME + " -c ";
 
=== modified file 'extensions/devpet.vala'
--- extensions/devpet.vala	2013-11-17 22:47:25 +0000
+++ extensions/devpet.vala	2014-02-28 21:47:46 +0000
@@ -193,7 +193,7 @@
                 void* buffer[100];
                 int num = Linux.backtrace (buffer, 100);
                 /* Upstream bug: https://git.gnome.org/browse/vala/commit/?id=f402af94e8471c8314ee7a312260a776e4d6fbe2 */
-                unowned string[] symbols = Midori.Linux.backtrace_symbols (buffer, num);
+                unowned string[] symbols = NotLinux.backtrace_symbols (buffer, num);
                 if (symbols != null) {
                     /* we don't need the first three lines */
                     for (int i = 3; i < num; i++) {
 
=== modified file 'extensions/history-list.vala'
--- extensions/history-list.vala	2013-10-28 22:33:16 +0000
+++ extensions/history-list.vala	2014-02-28 21:47:46 +0000
@@ -442,7 +442,7 @@
 
             if (this.history_window == null || this.history_window.get_type () != type) {
                 if (this.history_window == null) {
-                    this.modifier_count = Midori.Sokoke.gtk_action_count_modifiers (action);
+                    this.modifier_count = Sokoke.gtk_action_count_modifiers (action);
                     this.tmp_sig_ids[0] = browser.key_press_event.connect ((ek) => {
                         return this.key_press (ek);
                     });
 
=== modified file 'extensions/tabby.vala'
--- extensions/tabby.vala	2014-01-12 18:15:53 +0000
+++ extensions/tabby.vala	2014-02-28 21:47:46 +0000
@@ -710,7 +710,7 @@
                 for(int i = 0; uris[i] != null; i++) {
                     Katze.Item item = new Katze.Item ();
                     item.name = uris[i];
-                    item.uri = Midori.Sokoke.magic_uri (uris[i], true, true);
+                    item.uri = Sokoke.magic_uri (uris[i], true, true);
                     if (item.uri != null) {
                         tabs.add_item (item);
                     }
 
=== modified file 'katze/katze-item.c'
--- katze/katze-item.c	2013-08-05 19:52:52 +0000
+++ katze/katze-item.c	2014-02-28 21:47:46 +0000
@@ -499,8 +499,7 @@
  *
  * Return value: 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.4: as of 0.4.8 a @widget was added and the image is visible.
  **/
 GtkWidget*
 katze_item_get_image (KatzeItem* item,
@@ -637,9 +636,7 @@
  *
  * Return value: a string, or %NULL
  *
- * Since: 0.1.8
- *
- * Since 0.4.4 "" is treated like %NULL.
+ * Since: 0.1.8: as of 0.4.4 "" is treated like %NULL.
  **/
 const gchar*
 katze_item_get_meta_string (KatzeItem*   item,
 
=== modified file 'katze/katze-preferences.c'
--- katze/katze-preferences.c	2013-12-09 20:17:51 +0000
+++ katze/katze-preferences.c	2014-02-28 21:47:46 +0000
@@ -195,9 +195,7 @@
  *
  * Adds a new category with the specified label to the dialog.
  *
- * Since: 0.2.1
- *
- * Since 0.3.4 a #GtkBox is returned that can be packed into.
+ * Since: 0.2.1: as of 0.3.4 a #GtkBox is returned that can be packed into.
  **/
 GtkWidget*
 katze_preferences_add_category (KatzePreferences* preferences,
@@ -265,9 +263,7 @@
  *
  * Adds a new group with the specified label to the dialog.
  *
- * Since: 0.2.1
- *
- * Since 0.3.4 you can pass %NULL to hide the label.
+ * Since: 0.2.1: as of 0.3.4 you can pass %NULL to hide the label.
  **/
 void
 katze_preferences_add_group (KatzePreferences* preferences,
 
=== modified file 'katze/katze.vapi'
--- katze/katze.vapi	2014-02-22 14:06:19 +0000
+++ katze/katze.vapi	2014-02-28 21:47:46 +0000
@@ -3,6 +3,7 @@
 
 [CCode (cprefix = "Katze", lower_case_cprefix = "katze_")]
 namespace Katze {
+    public static string mkdir_with_parents (string pathname, int mode);
     static void assert_str_equal (string input, string result, string? expected);
     static unowned Gtk.Widget property_proxy (void* object, string property, string? hint);
     [CCode (cheader_filename = "katze/katze.h", cprefix = "KATZE_MENU_POSITION_")]
 
=== modified file 'midori/CMakeLists.txt'
--- midori/CMakeLists.txt	2013-09-08 21:38:36 +0000
+++ midori/CMakeLists.txt	2014-02-28 21:47:46 +0000
@@ -17,7 +17,8 @@
 PACKAGES
     ${PKGS}
 OPTIONS
-    ${VALAFLAGS}
+    ${VALACFLAGS}
+    --use-header="${CMAKE_PROJECT_NAME}-core.h"
 CUSTOM_VAPIS
     ${EXTRA_VAPIS}
 GENERATE_VAPI
 
=== modified file 'midori/midori-browser.c'
--- midori/midori-browser.c	2014-02-26 22:15:36 +0000
+++ midori/midori-browser.c	2014-02-28 21:47:46 +0000
@@ -2487,8 +2487,7 @@
     *
     * The speed dial configuration file.
     *
-    * Since: 0.3.4
-    * Since 0.4.7 this is a Midori.SpeedDial instance.
+    * Since: 0.3.4: as of 0.4.7 this is a Midori.SpeedDial instance.
     */
     g_object_class_install_property (gobject_class,
                                      PROP_SPEED_DIAL,
 
=== modified file 'midori/midori-download.vala'
--- midori/midori-download.vala	2014-02-22 22:35:42 +0000
+++ midori/midori-download.vala	2014-02-28 21:47:46 +0000
@@ -9,12 +9,6 @@
  See the file COPYING for the full license text.
 */
 
-namespace Sokoke {
-#if !HAVE_WEBKIT2
-    extern static bool message_dialog (Gtk.MessageType type, string short, string detailed, bool modal);
-#endif
-}
-
 namespace Midori {
     namespace Download {
         public static bool is_finished (WebKit.Download download) {
@@ -219,7 +213,7 @@
                     tab.open_uri (download.destination_uri);
             }
 
-            Sokoke.message_dialog (Gtk.MessageType.WARNING,
+            Midori.show_message_dialog (Gtk.MessageType.WARNING,
                 _("The downloaded file is erroneous."),
     _("The checksum provided with the link did not match. This means the file is probably incomplete or was modified afterwards."),
                 true);
@@ -304,7 +298,7 @@
             return filename;
         }
 
-        /**
+        /*
          * Returns a string showing a file:// URI's intended filename on
          * disk, suited for displaying to a user.
          * 
@@ -344,7 +338,7 @@
 
         /**
          * Returns whether it seems possible to save @download to the path specified by
-         * @destination_uri, considering space on disk and permissions
+         * destination_uri, considering space on disk and permissions
          */
         public static bool has_enough_space (WebKit.Download download, string destination_uri) {
 #if !HAVE_WEBKIT2
@@ -378,7 +372,7 @@
                 }
                 else
                     assert_not_reached ();
-                Sokoke.message_dialog (Gtk.MessageType.ERROR, message, detailed_message, false);
+                Midori.show_message_dialog (Gtk.MessageType.ERROR, message, detailed_message, false);
                 return false;
             }
 #endif
 
=== modified file 'midori/midori-speeddial.vala'
--- midori/midori-speeddial.vala	2013-10-28 23:08:02 +0000
+++ midori/midori-speeddial.vala	2014-02-28 21:47:46 +0000
@@ -9,14 +9,6 @@
  See the file COPYING for the full license text.
 */
 
-namespace Katze {
-    extern static string mkdir_with_parents (string pathname, int mode);
-}
-
-namespace Sokoke {
-    extern static string js_script_eval (void* ctx, string script, void* error);
-}
-
 namespace Midori {
     public errordomain SpeedDialError {
         INVALID_MESSAGE,
 
=== modified file 'midori/midori-view.c'
--- midori/midori-view.c	2014-02-22 22:35:42 +0000
+++ midori/midori-view.c	2014-02-28 21:47:46 +0000
@@ -225,9 +225,7 @@
      * @where determines where to open the view according
      * to how it was opened and user preferences.
      *
-     * Since: 0.1.2
-     *
-     * Since 0.3.4 a boolean argument was added.
+     * Since: 0.1.2 as of 0.3.4 a boolean argument was added.
      */
     signals[NEW_VIEW] = g_signal_new (
         "new-view",
 
=== modified file 'midori/midori.vapi'
--- midori/midori.vapi	2014-02-22 14:06:19 +0000
+++ midori/midori.vapi	2014-02-28 21:47:46 +0000
@@ -1,18 +1,17 @@
 /* Copyright (C) 2010 Christian Dywan <[e-mail]>
    This file is licensed under the terms of the expat license, see the file EXPAT. */
 
-public const string PACKAGE_NAME;
-
 [CCode (cprefix = "Midori", lower_case_cprefix = "midori_")]
 namespace Midori {
     public const string VERSION_SUFFIX;
+    [CCode (cheader_filename = "midori/midori-stock.h")]
     namespace Stock {
         public const string WEB_BROWSER;
         public const string TRANSFER;
         public const string PLUGINS;
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-frontend.h")]
     public static unowned Midori.Browser web_app_new (
         string webapp, [CCode (array_length = false)] string[]? uris, [CCode (array_length = false)] string[]? commands, int reset, string? block);
     public static unowned Midori.Browser private_app_new (string? config,
@@ -24,7 +23,7 @@
     [CCode (cheader_filename = "midori/midori-array.h")]
     public static bool array_from_file (Katze.Array array, string filename, string format) throws GLib.Error;
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-app.h")]
     public class App : GLib.Object {
         public App (string? name=null);
         public static void setup ([CCode (array_length_pos = 0.9)] ref unowned string[] args, [CCode (array_length = false)] GLib.OptionEntry[]? entries);
@@ -60,7 +59,7 @@
         public signal void quit ();
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-browser.h")]
     public class Browser : Gtk.Window {
         public Browser ();
         public unowned Gtk.Widget add_item (Katze.Item item);
@@ -121,13 +120,13 @@
         public signal void show_preferences (Katze.Preferences preferences);
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-panel.h")]
     public class Panel : Gtk.HBox {
         public Panel ();
         public int append_page (Midori.Viewable viewable);
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-extension.h")]
     public class Extension : GLib.Object {
         [CCode (has_construct_function = false)]
         public Extension ();
@@ -173,7 +172,7 @@
         public static void load_from_folder (Midori.App app, [CCode (array_length = false)] string[]? keys, bool activate);
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-view.h")]
     public class View : Tab {
         [CCode (type = "GtkWidget*")]
         public View.with_title (string? title=null, WebSettings? settings=null
@@ -214,13 +213,13 @@
         public signal void new_view (Midori.View new_view, Midori.NewView where, bool user_initiated);
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-locationaction.h")]
     public class LocationAction : Gtk.Action {
         public static string render_uri ([CCode (array_length = false)] string[] keys, string uri_escaped);
         public static string render_title ([CCode (array_length = false)] string[] keys, string title);
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-searchaction.h")]
     public class SearchAction : Gtk.Action {
         public static Katze.Item? get_engine_for_form (WebKit.WebView web_view, Pango.EllipsizeMode ellipsize);
     }
@@ -241,7 +240,7 @@
         PENDING_UNDELAY,
     }
 
-    [CCode (cheader_filename = "midori/midori.h")]
+    [CCode (cheader_filename = "midori/midori-websettings.h")]
     public class WebSettings : Midori.Settings {
         public WebSettings ();
         [NoAccessorMethod]
@@ -257,23 +256,5 @@
         LAST_OPEN_PAGES,
         DELAYED_PAGES
     }
-
-    [CCode (cheader_filename = "midori/sokoke.h", lower_case_cprefix = "sokoke_")]
-    namespace Sokoke {
-        public static string magic_uri (string uri, bool allow_search, bool allow_relative);
-        public static uint gtk_action_count_modifiers (Gtk.Action action);
-    #if HAVE_WIN32
-        public static string get_win32_desktop_lnk_path_for_filename (string filename);
-        public static void create_win32_desktop_lnk (string prefix, string filename, string uri);
-    #endif
-    }
-
-    #if HAVE_EXECINFO_H
-    [CCode (lower_case_cprefix = "")]
-    namespace Linux {
-        [CCode (cheader_filename = "execinfo.h", array_length = false)]
-        public unowned string[] backtrace_symbols (void* buffer, int size);
-    }
-    #endif
 }
 
 
=== added file 'midori/sokoke.vapi'
--- midori/sokoke.vapi	1970-01-01 00:00:00 +0000
+++ midori/sokoke.vapi	2014-02-28 21:47:46 +0000
@@ -0,0 +1,22 @@
+/* Copyright (C) 2010 Christian Dywan <[e-mail]>
+   This file is licensed under the terms of the expat license, see the file EXPAT. */
+
+[CCode (cheader_filename = "midori/sokoke.h", lower_case_cprefix = "sokoke_")]
+namespace Sokoke {
+    public static string magic_uri (string uri, bool allow_search, bool allow_relative);
+    public static uint gtk_action_count_modifiers (Gtk.Action action);
+#if HAVE_WIN32
+    public static string get_win32_desktop_lnk_path_for_filename (string filename);
+    public static void create_win32_desktop_lnk (string prefix, string filename, string uri);
+#endif
+    public static string js_script_eval (void* ctx, string script, void* error);
+}
+
+#if HAVE_EXECINFO_H
+[CCode (lower_case_cprefix = "")]
+namespace NotLinux {
+    [CCode (cheader_filename = "execinfo.h", array_length = false)]
+    public unowned string[] backtrace_symbols (void* buffer, int size);
+}
+#endif
+
 
=== modified file 'tests/CMakeLists.txt'
--- tests/CMakeLists.txt	2013-10-01 21:35:39 +0000
+++ tests/CMakeLists.txt	2014-02-28 21:47:46 +0000
@@ -22,11 +22,10 @@
         PACKAGES
             ${PKGS}
         OPTIONS
-            ${VALAFLAGS}
+            ${VALACFLAGS}
         CUSTOM_VAPIS
             ${EXTRA_VAPIS}
             "${CMAKE_SOURCE_DIR}/midori/midori.vapi"
-            "${CMAKE_SOURCE_DIR}/katze/katze.vapi"
             "${CMAKE_BINARY_DIR}/midori/${LIBMIDORI}.vapi"
         )