chrome/browser/extensions/api/README.txt

   1 This file describes steps and files needed when adding a new API to Chrome.
   2 Before you start coding your new API, though, make sure you follow the process
   3 described at:
   4   http://www.chromium.org/developers/design-documents/extensions/proposed-changes/apis-under-development
   5
   6 Two approaches are available for writing your API specification. The original
   7 approach relies on JSON specification files. The more recent and simpler system
   8 uses Web IDL files, but does not yet support all the features of the JSON files.
   9 Discuss with a member of the extensions team (aa@chromium.org) before you decide
  10 which approach is better suited to your API.
  11
  12 The following steps suppose you're writing an experimental API called "Foo".
  13
  14 --------------------------------------------------------------------------------
  15 APPROACH 1: JSON FILES
  16
  17 1) Write your API specification.
  18 Create "chrome/common/extensions/api/experimental_foo.json". For inspiration
  19 look at the "app" API. Include descriptions fields to generate the
  20 documentation.
  21
  22 2) Add your API specification to api.gyp.
  23 Add "experimental_foo.json" to the "schema_files" section in
  24 "chrome/common/extensions/api/api.gyp".
  25
  26 3) Write the API function handlers.
  27 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You
  28 should use the JSON Schema Compiler. Look at the "permissions_api.cc" for
  29 details on how to do that.
  30
  31 --------------------------------------------------------------------------------
  32 APPROACH 2: IDL FILES
  33
  34 1) Write your API specification.
  35 Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look
  36 at "alarms.idl". Include comments, they will be used to automatically generate
  37 the documentation.
  38
  39 2) Add your API specification to api.gyp.
  40 Add "experimental_foo.idl" to the "schema_files" section in
  41 "chrome/common/extensions/api/api.gyp".
  42
  43 3) Write the API function handlers.
  44 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You
  45 should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on
  46 how to do that.
  47
  48 --------------------------------------------------------------------------------
  49 STEPS COMMON TO BOTH APPROACHES
  50
  51 6) Write support classes for your API
  52 If your API needs any support classes add them to
  53 "chrome/browser/extensions/api/foo". Some old APIs added their support classes
  54 directly to chrome/browser/extensions. Don't do that.
  55
  56 7) Update the project with your new files.
  57 The files you created in (3) and (5) should be added to
  58 "chrome/chrome_browser_extensions.gypi".
  59
  60 --------------------------------------------------------------------------------
  61 GENERATING DOCUMENTATION
  62
  63 8) Add a stub template in ../docs/templates/public corresponding to your API.
  64 See other templates for inspiration.
  65
  66 9) Run ../docs/templates/server2/preview.py to view the generated documentation.
  67
  68 --------------------------------------------------------------------------------
  69 WRITING TESTS
  70
  71 12) Write a unit test for your API.
  72 Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of
  73 your API methods. See "alarms_api_unittest.cc" for details. Once done add your
  74 .cc to "chrome/chrome_tests.gypi".