Adding new API to WebKit2 GTK+

• Patches including new public API should be approved by at least two reviewers
• Patches should include API documentation for new methods, properties, signals, etc.
  • See ​http://developer.gnome.org/gtk-doc-manual/stable/
  • Include gobject introspection annotations too. See ​http://live.gnome.org/GObjectIntrospection/Annotations
  • Use always 'Returns:' instead of 'Return value:', just for consistency, in methods returning a value.
  • Remember to update the sections file (​UIProcess/API/gtk/docs/webkit2gtk-sections.txt) with new symbols.
  • If the patch adds a new public class, add the get_type() method to file ​UIProcess/API/gtk/docs/webkit2gtk.types
  • If the patch adds a new section, remember to update the file ​UIProcess/API/gtk/docs/webkit2gtk-docs.sgml too
• Patches should always include unit tests for new API when possible
• If the patch adds a new public header
  • Remember to add it to webkit2gtk_headers variable in ​GNUmakefile.am file
  • Add a new #include for it to the ​main WebKit2 header
• Follow coding style guidelines
  • Use GNOME coding style for public headers and generated code (get_type(), init() and class_init() methods)
  • Use WebKit coding style for all other code, including unit tests, See ​http://www.webkit.org/coding/coding-style.html
  • You can use check-webkit-style script to make sure your patch follows the WebKit coding style
• Use the placement new syntax for private structures
  • Let glib allocate the private structure using g_type_class_add_private() as usual
  • In the init method use the following syntax

    static void webkit_foo_init(WebKitFoo* foo)
    {
        WebKitFooPrivate* priv = G_TYPE_INSTANCE_GET_PRIVATE(foo, WEBKIT_TYPE_FOO, WebKitFooPrivate);
        foo->priv = priv;
        new (priv) WebKitFooPrivate();
    }
    

  • And in finalize method call the destructor manually

    static void webkitFooFinalize(GObject* object)
    {
        WEBKIT_FOO(object)->priv->~WebKitFooPrivate();
        G_OBJECT_CLASS(webkit_foo_parent_class)->finalize(object);
    }
    

• Use wtf classes (CString, HashMap, etc.) and GRefPtr/GOwnPtr for attributes so that they are automatically freed by the private structure destructor
• 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.
• Use GObject properties only for attributes that can change their value at any time, so that users can monitor them connecting to notify signal.
• Add always public get/set methods even for attributes that are GObject properties
• Protect arguments of public methods using g_return_if_fail() and g_return_val_if_fail() macros
  • For private methods use ASSERT or g_assert() instead, but only when it's really needed
• 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):

  #if !defined(__WEBKIT2_H_INSIDE__) && !defined(WEBKIT2_COMPILATION)
  #error "Only <webkit2/webkit2.h> can be included directly."
  #endif
  
  #ifndef WebKitFoo_h
  #define WebKitFoo_h
  .......
  

• Don't expose the C API in public API or headers
• Including other headers:
  • Use always the angle-bracket form of #include directive in public headers
  • In private headers or .cpp files
    • Use the angle-bracket form for header files from other libraries, including WebCore, JavaScriptCore or the WebKit2 C API
    • Use the quoted form for header files of WebKit2