| 53 | | |
| 54 | | == Working on WebCore == |
| 55 | | |
| 56 | | * The GTK+ elements of WebCore follow the WebKit coding style. |
| 57 | | |
| 58 | | * There is no API stability in this layer. If an abstraction does not fit GTK+/Cairo/GStreamer/Libsoup concepts, feel free to seek advice on how to generalise the abstraction layer. This should not be necessary too often though. |
| 59 | | |
| 60 | | * Documentation is generally avoided in favour of clear, self-explanatory code and good variable names. |
| 61 | | |
| 62 | | == Working on the public API == |
| 63 | | |
| 64 | | * Follow the precedent set by the Mac and Win ports. There is [http://developer.apple.com/documentation/Cocoa/Reference/WebKit/ObjC_classic/index.html Mac API documentation] available for reference. |
| 65 | | |
| 66 | | * Document new additions with [http://live.gnome.org/DocumentationProject/GtkDoc GtkDoc]. It is OK to base GTK+ API documentation on the Objective-C documentation, but remember that "the receiver" will be "@this" or similar in GTK+ terminology, and a "method" translates to a "function" etc. |
| 67 | | |
| 68 | | * If you find mistakes in the Objective-C API documentation, take notes and add them in the comments of your bug report. |
| 69 | | |
| 70 | | * Check function parameters with g_return_if_fail() and g_return_val_if_fail() |
| 71 | | |
| 72 | | * Don't use the abbreviation "URL" or "url" in any public API headers or documentation. Instead, use "URI" or "uri". This is a strong convention in GLib/GTK+ which deviates from the one used in WebCore and other WebKit ports. |
| 73 | | * Recommendation: Internally, relevant gchar* variables to be passed to or from the user should also be named "uri" until parsed into a KURL or WebCore data structure, at which point they should be called "url". |
| 74 | | |
| 75 | | * Try to implement several functions at the same time to get a better understanding of how they work together and to improve consistency. This is more effective than just implementing functions and signals one by one as needed. |
| 76 | | |
| 77 | | * Avoid drawing inspiration from ports other than Mac and Win, since they might have decided to follow their own interpretation. This is like going for the primary sources in a research project. |
| 78 | | |
| 79 | | * If a method looks strange or out of place, '''ask questions''' until someone explains why it is the way it is. The Mac port may contain deprecated/bad API that exists only for the sake of compatibility -- we want to learn from those mistakes rather than copying them. |
| 80 | | |
| 81 | | * See [wiki:"WebKitGTK/AddingNewWebKit2API" AddingNewWebKit2API] for WebKit2 guidelines |
| 82 | | |
| 83 | | == API rationale == |
| 84 | | |
| 85 | | The strategy here is to develop a GObject-based interpretation of the Objective-C API combined with experience working with GtkTextView, GtkHtml and gtkmozembed. This allows us to benefit from the maturity of a widely-deployed API, but demands extra caution not to adopt any of the baggage or legacy that might be present for backward compatibility only. The Win port is also a useful resource but is less suitable for direct inspiration since it hasn't been deployed as a stable API yet and has a large API footprint that would be difficult to support in the long term. |
| 86 | | |
| 87 | | For more information, check out the [http://webkitgtk.org/reference/webkitgtk/stable/index.html API reference] on the official WebKit GTK+ page. |
| 88 | | == The build bots == |
| 89 | | |
| 90 | | There is a [http://build.webkit.org/ build bot] available for most ports including GTK+. The [http://build.webkit.org/waterfall waterfall view] is particularly useful. |
| 91 | | |
| 92 | | This helps keep all the ports buildable. There is also compile output provided which is helpful for understanding the build environments and compiler flags used by other ports and tracking down compiler warnings. |
| 93 | | |
| 94 | | == LayoutTests == |
| 95 | | |
| 96 | | See [http://trac.webkit.org/wiki/WebKitGtkLayoutTests WebKitGTK+ Layout Tests] |
| 97 | | |
| 98 | | == Optimization == |
| 99 | | |
| 100 | | See [wiki:"OptimizingGtk" the hacker's guide to optimizing WebKit/GTK+]. |
