Add section information for View, Frame, Settings, HistoryItem, BackForwardList,...
authorzecke@webkit.org <zecke@webkit.org@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Wed, 31 Dec 2008 17:52:47 +0000 (17:52 +0000)
committerzecke@webkit.org <zecke@webkit.org@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Wed, 31 Dec 2008 17:52:47 +0000 (17:52 +0000)
Add section information and informal examples for WebKitWebView,
WebKitWebFrame, WebKitWebSettings, WebKitWebNetworkRequest,
WebKitWebWindowFeatures, WebKitWebHistoryItem,
WebKitWebBackForwardList and WebKitWebInspector.

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@39532 268f45cc-cd09-0410-ab3c-d52691b4dbfc

12 files changed:
WebKit/gtk/ChangeLog
WebKit/gtk/docs/webkitgtk-sections.txt
WebKit/gtk/webkit/webkitnetworkrequest.cpp
WebKit/gtk/webkit/webkitwebbackforwardlist.cpp
WebKit/gtk/webkit/webkitwebframe.cpp
WebKit/gtk/webkit/webkitwebhistoryitem.cpp
WebKit/gtk/webkit/webkitwebhistoryitem.h
WebKit/gtk/webkit/webkitwebinspector.cpp
WebKit/gtk/webkit/webkitwebsettings.cpp
WebKit/gtk/webkit/webkitwebsettings.h
WebKit/gtk/webkit/webkitwebview.cpp
WebKit/gtk/webkit/webkitwebwindowfeatures.cpp

index 19753cf..cf19d62 100644 (file)
@@ -1,3 +1,28 @@
+2008-12-31  Holger Hans Peter Freyther  <zecke@selfish.org>
+
+        Reviewed by Nikolas Zimmermann.
+
+        https://bugs.webkit.org/show_bug.cgi?id=17045
+
+        Add section information for View, Frame, Settings, HistoryItem, BackForwardList, WindowFeatures and Inspector
+
+        Add section information and informal examples for WebKitWebView,
+        WebKitWebFrame, WebKitWebSettings, WebKitWebNetworkRequest,
+        WebKitWebWindowFeatures, WebKitWebHistoryItem,
+        WebKitWebBackForwardList and WebKitWebInspector.
+
+        * docs/webkitgtk-sections.txt: Decide to not document some bits
+        * webkit/webkitnetworkrequest.cpp:
+        * webkit/webkitwebbackforwardlist.cpp:
+        * webkit/webkitwebframe.cpp:
+        * webkit/webkitwebhistoryitem.cpp:
+        * webkit/webkitwebhistoryitem.h:
+        * webkit/webkitwebinspector.cpp:
+        * webkit/webkitwebsettings.cpp:
+        * webkit/webkitwebsettings.h:
+        * webkit/webkitwebview.cpp:
+        * webkit/webkitwebwindowfeatures.cpp:
+
 2008-12-21  Xan Lopez  <xan@gnome.org>
 
         Reviewed by Holger Freyther.
index 2f9cc59..d20bc7a 100644 (file)
@@ -132,8 +132,6 @@ WebKitWebInspectorClass
 <TITLE>WebKitNetworkRequest</TITLE>
 WebKitNetworkRequest
 webkit_network_request_get_uri
-webkit_network_request_new
-webkit_network_request_set_uri
 <SUBSECTION Standard>
 WEBKIT_NETWORK_REQUEST
 WEBKIT_IS_NETWORK_REQUEST
@@ -143,6 +141,8 @@ WEBKIT_IS_NETWORK_REQUEST_CLASS
 WEBKIT_NETWORK_REQUEST_GET_CLASS
 <SUBSECTION Private>
 webkit_network_request_get_type
+webkit_network_request_new
+webkit_network_request_set_uri
 WebKitNetworkRequestPrivate
 WebKitNetworkRequest
 WebKitNetworkRequestClass
@@ -202,7 +202,6 @@ webkit_web_view_unmark_text_matches
 webkit_web_view_zoom_in
 webkit_web_view_zoom_out
 webkit_web_view_get_window_features
-webkit_web_view_set_window_features
 <SUBSECTION Standard>
 WEBKIT_WEB_VIEW
 WEBKIT_IS_WEB_VIEW
@@ -211,6 +210,7 @@ WEBKIT_WEB_VIEW_CLASS
 WEBKIT_IS_WEB_VIEW_CLASS
 WEBKIT_WEB_VIEW_GET_CLASS
 <SUBSECTION Private>
+webkit_web_view_set_window_features
 webkit_web_view_get_type
 WebKitWebViewPrivate
 WebKitWebView
index fab0f88..3ad8b5d 100644 (file)
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2007 Holger Hans Peter Freyther
+ * Copyright (C) 2007, 2008 Holger Hans Peter Freyther
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
 
 #include "webkitnetworkrequest.h"
 
+/**
+ * SECTION:webkitnetworkrequest
+ * @short_description: The target of a navigation request
+ * @see_also: #WebKitWebView::navigation-requested
+ *
+ * This class represents the network related aspects of a navigation
+ * request. Currently this is only the uri of the target. In the future
+ * the state of the web form might be added.
+ * Currently this object is only used along with the
+ * #WebKitWebView::navigation-requested signal.
+ *
+ */
+
 extern "C" {
 
 G_DEFINE_TYPE(WebKitNetworkRequest, webkit_network_request, G_TYPE_OBJECT);
@@ -77,6 +90,14 @@ void webkit_network_request_set_uri(WebKitNetworkRequest* request, const gchar*
     priv->uri = g_strdup(uri);
 }
 
+/**
+ * webkit_network_request_get_uri:
+ * @request: a #WebKitNetworkRequest
+ *
+ * Returns: the uri of the #WebKitNetworkRequest
+ *
+ * Since: 1.0.0
+ */
 G_CONST_RETURN gchar* webkit_network_request_get_uri(WebKitNetworkRequest* request)
 {
     g_return_val_if_fail(WEBKIT_IS_NETWORK_REQUEST(request), NULL);
index f0d6a79..3899f4b 100644 (file)
 #include "BackForwardList.h"
 #include "HistoryItem.h"
 
+/**
+ * SECTION:webkitwebbackforwardlist
+ * @short_description: The history of a #WebKitWebView
+ * @see_also: #WebKitWebView, #WebKitWebHistoryItem
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Get the WebKitWebBackForwardList from the WebKitWebView *<!-- -->/
+ * WebKitWebBackForwardList *back_forward_list = webkit_web_view_get_back_forward_list (my_web_view);
+ * WebKitWebHistoryItem *item = webkit_web_back_forward_list_get_current_item (back_forward_list);
+ *
+ * /<!-- -->* Do something with a WebKitWebHistoryItem *<!-- -->/
+ * g_print("%p", item);
+ *
+ * /<!-- -->* Control some parameters *<!-- -->/
+ * WebKitWebBackForwardList *back_forward_list = webkit_web_view_get_back_forward_list (my_web_view);
+ * webkit_web_back_forward_list_set_limit (back_forward_list, 30);
+ * </programlisting></informalexample>
+ *
+ */
+
 using namespace WebKit;
 
 extern "C" {
index ff4ff1e..c42621a 100644 (file)
 
 #include <JavaScriptCore/APICast.h>
 
+/**
+ * SECTION:webkitwebframe
+ * @short_description: The content of a #WebKitWebView
+ *
+ * A #WebKitWebView contains a main #WebKitWebFrame. A #WebKitWebFrame
+ * contains the content of one URI. The URI and name of the frame can
+ * be retrieved, the load status and progress can be observed using the
+ * signals and can be controlled using the methods of the #WebKitWebFrame.
+ * A #WebKitWebFrame can have any number of children and one child can
+ * be found by using #webkit_web_frame_find_frame.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Get the frame from the #WebKitWebView *<!-- -->/
+ * WebKitWebFrame *frame = webkit_web_view_get_main_frame (WEBKIT_WEB_VIEW(my_view));
+ * g_print("The URI of this frame is '%s'", webkit_web_frame_get_uri (frame));
+ * </programlisting></informalexample>
+ */
+
 using namespace WebKit;
 using namespace WebCore;
 using namespace std;
index 60b1746..8cdaa90 100644 (file)
 #include "HistoryItem.h"
 #include "PlatformString.h"
 
+/**
+ * SECTION:webkitwebhistoryitem
+ * @short_description: One item of the #WebKitWebBackForwardList and or global history
+ * @see_also: #WebKitWebBackForwardList
+ *
+ * A history item consists out of a title and a uri. It can be part of the
+ * #WebKitWebBackForwardList and the global history. The global history is used
+ * for coloring the links of visited sites.  #WebKitHistoryItem's constructed with
+ * #webkit_web_history_item_new and #webkit_web_history_item_new_with_data are
+ * automatically added to the global history.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Inject a visited page into the global history *<!-- -->/
+ * webkit_web_history_item_new_with_data("http://www.gnome.org/", "GNOME: The Free Software Desktop Project");
+ * webkit_web_history_item_new_with_data("http://www.webkit.org/", "The WebKit Open Source Project");
+ * </programlisting></informalexample>
+ *
+ */
+
 using namespace WebKit;
 
 extern "C" {
index dd63f9d..f870a0d 100644 (file)
@@ -39,6 +39,7 @@ typedef struct _WebKitWebHistoryItemPrivate WebKitWebHistoryItemPrivate;
 struct _WebKitWebHistoryItem {
     GObject parent_instance;
 
+    /*< private >*/
     WebKitWebHistoryItemPrivate *priv;
 };
 
index 9199b1c..b8f8d9e 100644 (file)
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2008 Gustavo Noronha Silva
+ * Copyright (C) 2008 Holger Hans Peter Freyther
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
 #include "InspectorClientGtk.h"
 #include "webkitprivate.h"
 
+/**
+ * SECTION:webkitwebinspector
+ * @short_description: Access to the WebKit Inspector
+ *
+ * The WebKit Inspector is a graphical tool to inspect and change
+ * the content of a #WebKitWebView. It also includes an interactive
+ * JavaScriptDebugger. Using this class one can get a GtkWidget which
+ * can be embedded into an application to show the inspector.
+ *
+ * The inspector is available when the #WebKitWebSettings of the
+ * #WebKitWebView has set the #WebKitWebSettings:enable-developer-extras
+ * to true otherwise no inspector is available.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Enable the developer extras *<!-- -->/
+ * WebKitWebSettings *setting = webkit_web_view_get_settings (WEBKIT_WEB_VIEW(my_webview));
+ * g_object_set (G_OBJECT(settings), "enable-developer-extras", TRUE, NULL);
+ *
+ * /<!-- -->* load some data or reload to be able to inspect the page*<!-- -->/
+ * webkit_web_view_open (WEBKIT_WEB_VIEW(my_webview), "http://www.gnome.org");
+ *
+ * /<!-- -->* Embed the inspector somewhere *<!-- -->/
+ * WebKitWebInspector *inspector = webkit_web_view_get_inspector (WEBKIT_WEB_VIEW(my_webview));
+ * g_signal_connect (G_OBJECT (inspector), "inspect-web-view", G_CALLBACK(create_gtk_window_around_it), NULL);
+ * g_signal_connect (G_OBJECT (inspector), "show-window", G_CALLBACK(show_inpector_window), NULL));
+ * g_signal_connect (G_OBJECT (inspector), "notify::inspected-uri", G_CALLBACK(inspected_uri_changed_do_stuff), NULL);
+ * </programlisting></informalexample>
+ */
+
 using namespace WebKit;
 
 extern "C" {
index d0cabda..aa38c6c 100644 (file)
@@ -2,6 +2,7 @@
  * Copyright (C) 2008 Christian Dywan <christian@imendio.com>
  * Copyright (C) 2008 Nuanti Ltd.
  * Copyright (C) 2008 Collabora Ltd.
+ * Copyright (C) 2008 Holger Hans Peter Freyther
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
 #include "FileSystem.h"
 #include "PluginDatabase.h"
 
+/**
+ * SECTION:webkitwebsettings
+ * @short_description: Control the behaviour of a #WebKitWebView
+ *
+ * #WebKitWebSettings can be applied to a #WebKitWebView to control
+ * the to be used text encoding, color, font sizes, printing mode,
+ * script support, loading of images and various other things.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Create a new websettings and disable java script *<!-- -->/
+ * WebKitWebSettings *settings = webkit_web_settings_new ();
+ * g_object_set (G_OBJECT(settings), "enable-scripts", FALSE, NULL);
+ *
+ * /<!-- -->* Apply the result *<!-- -->/
+ * webkit_web_view_set_settings (WEBKIT_WEB_VIEW(my_webview), settings);
+ * </programlisting></informalexample>
+ */
+
 using namespace WebCore;
 
 extern "C" {
index 33fa54a..5d25fee 100644 (file)
@@ -38,6 +38,7 @@ typedef struct _WebKitWebSettingsPrivate WebKitWebSettingsPrivate;
 struct _WebKitWebSettings {
     GObject parent_instance;
 
+    /*< private >*/
     WebKitWebSettingsPrivate *priv;
 };
 
index e98d3f7..7c5976f 100644 (file)
@@ -1,5 +1,5 @@
 /*
- *  Copyright (C) 2007 Holger Hans Peter Freyther
+ *  Copyright (C) 2007, 2008 Holger Hans Peter Freyther
  *  Copyright (C) 2007, 2008 Christian Dywan <christian@imendio.com>
  *  Copyright (C) 2007 Xan Lopez <xan@gnome.org>
  *  Copyright (C) 2007, 2008 Alp Toker <alp@atoker.com>
 
 #include <gdk/gdkkeysyms.h>
 
+/**
+ * SECTION:webkitwebview
+ * @short_description: The central class of the WebKit/Gtk+ API
+ * @see_also: #WebKitWebSettings, #WebKitWebFrame
+ *
+ * #WebKitWebView is the central class of the WebKit/Gtk+ API. It is a
+ * #GtkWidget implementing the scrolling interface which means you can
+ * embed in a #GtkScrolledWindow. It is responsible for managing the
+ * drawing of the content, forwarding of events. You can load any URI
+ * into the #WebKitWebView or any kind of data string. With #WebKitWebSettings
+ * you can control various aspects of the rendering and loading of the content.
+ * Each #WebKitWebView has exactly one #WebKitWebFrame as main frame. A
+ * #WebKitWebFrame can have n children.
+ *
+ * <programlisting>
+ * /<!-- -->* Create the widgets *<!-- -->/
+ * GtkWidget *main_window = gtk_window_new (GTK_WIDGET_TOPLEVEL);
+ * GtkWidget *scrolled_window = gtk_scrolled_window_new (NULL, NULL);
+ * GtkWidget *web_view = webkit_web_view_new ();
+ *
+ * /<!-- -->* Place the WebKitWebView in the GtkScrolledWindow *<!-- -->/
+ * gtk_container_add (GTK_CONTAINER (scrolled_window), web_view);
+ * gtk_container_add (GTK_CONTAINER (main_window), scrolled_window);
+ *
+ * /<!-- -->* Open a webpage *<!-- -->/
+ * webkit_web_view_open (WEBKIT_WEB_VIEW (web_view), "http://www.gnome.org");
+ *
+ * /<!-- -->* Show the result *<!-- -->/
+ * gtk_window_set_default_size (GTK_WINDOW (main_window), 800, 600);
+ * gtk_widget_show_all (main_window);
+ * </programlisting>
+ */
+
 static const double defaultDPI = 96.0;
 
 using namespace WebKit;
index 3bbbc6c..7e61b59 100644 (file)
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2008 Gustavo Noronha Silva <gns@gnome.org>
+ * Copyright (C) 2008 Holger Hans Peter Freyther
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
 #include "webkitwebwindowfeatures.h"
 #include "webkitprivate.h"
 
+/**
+ * SECTION:webkitwebwindowfeatures
+ * @short_description: Window properties of a #WebKitWebView
+ * @see_also: #WebKitWebView::web-view-ready
+ *
+ * The content of a #WebKitWebView can request to change certain
+ * properties of a #WebKitWebView. This can include the x, y position
+ * of the window, the width and height but also if a toolbar,
+ * scrollbar, statusbar, locationbar should be visible to the user,
+ * the request to show the #WebKitWebView fullscreen.
+ *
+ * In the normal case one will use #webkit_web_view_get_window_features
+ * to get the #WebKitWebWindowFeatures and then monitor the property
+ * changes. Be aware that the #WebKitWebWindowFeatures might change
+ * change before #WebKitWebView::web-view-ready signal is emitted.
+ * To be safe listen to the notify::window-features signal of the #WebKitWebView
+ * and reconnect the signals whenever the #WebKitWebWindowFeatures of
+ * a #WebKitWebView changes.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Get the current WebKitWebWindowFeatures *<!-- -->/
+ * WebKitWebWindowFeatures *features = webkit_web_view_get_window_features (my_webview);
+ *
+ * /<!-- -->* Connect to the property changes *<!-- -->/
+ * g_signal_connect (G_OBJECT(features), "notify::menubar-visible", G_CALLBACK(make_menu_bar_visible), NULL);
+ * g_signal_connect (G_OBJECT(features), "notify::statusbar-visible", G_CALLBACK(make_status_bar_visible), NULL);
+ *
+ * </programlisting></informalexample>
+ */
+
 extern "C" {
 
 enum {