src/third_party/WebKit/public/README

   1 Blink Public API
   2 ================
   3
   4 This directory contains the public API for Blink. The API consists of a number
   5 of C++ header files, scripts, and GYP build files. We consider all other files
   6 in Blink to be implementation details, which are subject to change at any time
   7 without notice.
   8
   9 The primary consumer of this API is Chromium's Content layer. If you are
  10 interested in using Blink, please consider interfacing with Blink via the
  11 Content layer rather than interfacing directly with this API.
  12
  13 Compatibility
  14 -------------
  15
  16 The API does not support binary compatibility. Instead, the API is intended to
  17 insulate the rest of the Chromium project from internal changes to Blink.  Over
  18 time, the API is likely to evolve in source-incompatible ways as Chromium's and
  19 Blink's needs change.
  20
  21 Organization
  22 ------------
  23
  24 The API is organized into three parts:
  25
  26   - public/platform
  27   - public/web
  28   - public/testing
  29
  30 The public/platform directory defines an abstract platform upon which Blink
  31 runs. Rather than communicating directly with the underlying operating system,
  32 Blink is designed to run in a sandbox and interacts with the operating system
  33 via the platform API. The central interface in this part of the API is
  34 Platform, which is a pure virtual interface from which Blink obtains many other
  35 interfaces.
  36
  37 The public/web directory defines an interface to Blink's implementation of the
  38 web platform, including the Document Object Model (DOM). The central interface
  39 in this part of the API is WebView, which is a good starting point for
  40 exploring the API.
  41
  42 Note that public/platform should not depend on public/web.
  43
  44 The public/testing directory defines an interface for testing Blink. You can
  45 use this part of the API to load the TestRunner module used in Blink's test
  46 suite.
  47
  48 Basic Types
  49 -----------
  50
  51 The API does not use STL types, except for a small number of STL types that are
  52 used internally by Blink (e.g., std::pair). Instead, we use WTF containers to
  53 implement the API.
  54
  55 The API uses some internal types (e.g., WebCore::Node). Typically, these types
  56 are forward declared and are opaque to consumers of the API. In other cases,
  57 the full definitions are available behind the BLINK_IMPLEMENTATION
  58 preprocessor macro. In both cases, we continue to regard these internal types
  59 as implementation details of Blink, and consumers of the API should not rely
  60 upon these types.
  61
  62 Similarly, the API uses STL types outside of the BLINK_IMPLEMENTATION
  63 preprocessor macro, which is for the convenience of the consumer.
  64
  65 Contact Information
  66 -------------------
  67
  68 The public API also contains an OWNERS file, which lists a number of people who
  69 are knowledgeable about the API. If you have questions or comments about the
  70 API that might be of general interest to the Blink community at large, please
  71 consider directing your inquiry to blink-dev@chromium.org rather than to the
  72 OWNERS specifically.