Changes between Initial Version and Version 1 of WebKitGTK/AddingNewWebKit2API


Ignore:
Timestamp:
Oct 21, 2011 3:05:45 AM (12 years ago)
Author:
Carlos Garcia Campos
Comment:

Initial guidelines for adding new API to WebKit2 GTK+

Legend:

Unmodified
Added
Removed
Modified
  • WebKitGTK/AddingNewWebKit2API

    v1 v1  
     1= Adding new API to WebKit2 GTK+ =
     2
     3 * Patches including new public API should be approved by at least two reviewers
     4 * Patches should include API documentation for new methods, properties, signals, etc.
     5  * See http://developer.gnome.org/gtk-doc-manual/stable/
     6  * Include gobject introspection annotations too. See http://live.gnome.org/GObjectIntrospection/Annotations
     7  * Use always 'Returns:' instead of 'Return value:', just for consistency, in methods returning a value.
     8  * Remember to update the sections file ([http://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-sections.txt UIProcess/API/gtk/docs/webkit2gtk-sections.txt]) with new symbols.
     9  * If the patch adds a new public class, add the get_type() method to file [http://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk.types UIProcess/API/gtk/docs/webkit2gtk.types]
     10  * If the patch adds a new section, remember to update the file [http://trac.webkit.org/browser/trunk/Source/WebKit2/UIProcess/API/gtk/docs/webkit2gtk-docs.sgml UIProcess/API/gtk/docs/webkit2gtk-docs.sgml] too
     11 * Patches should always include unit tests for new API when possible
     12 * Follow coding style guidelines
     13  * Use GNOME coding style for public headers and generated code (get_type(), init() and class_init() methods)
     14  * Use WebKit coding style for all other code, including unit tests, See http://www.webkit.org/coding/coding-style.html
     15  * You can use check-webkit-style script to make sure your patch follows the WebKit coding style
     16 * Use the placement new syntax for private structures
     17  * Let glib allocate the private structure using g_type_class_add_private() as usual
     18  * In the init method use the following syntax
     19  {{{
     20static void webkit_foo_init(WebKitFoo* foo)
     21{
     22    WebKitFooPrivate* priv = G_TYPE_INSTANCE_GET_PRIVATE(foo, WEBKIT_TYPE_FOO, WebKitFooPrivate);
     23    foo->priv = priv;
     24    new (priv) WebKitFooPrivate();
     25}
     26  }}}
     27  * And in finalize method call the destructor manually
     28  {{{
     29static void webkitFooFinalize(GObject* object)
     30{
     31    WEBKIT_FOO(object)->priv->~WebKitFooPrivate();
     32    G_OBJECT_CLASS(webkit_foo_parent_class)->finalize(object);
     33}
     34  }}}
     35 * Use wtf classes (CString, HashMap, etc.) and GRefPtr/GOwnPtr for attributes so that they are automatically freed by the private structure destructor
     36 * Don't make private structures public in Private.h headers, keep them in the corresponding .cpp file and add private API for accessing them when needed.
     37 * Use GObject properties only for attributes that can change their value at any time, so that users can monitor them connecting to notify signal.
     38 * Add always public get/set methods even for attributes that are GObject properties
     39 * Protect arguments of public methods using g_return_if_fail() and g_return_val_if_fail() macros
     40  * For private methods use ASSERT or g_assert() instead, but only when it's really needed
     41 * Protect public headers so that they can't be included directly in client code, adding the following code at the top of the file (after the license text):
     42 {{{
     43#if !defined(__WEBKIT2_H_INSIDE__) && !defined(WEBKIT2_COMPILATION)
     44#error "Only <webkit2/webkit2.h> can be included directly."
     45#endif
     46
     47#ifndef WebKitFoo_h
     48#define WebKitFoo_h
     49.......
     50 }}}