[Extensions] Add starter documentation for extension features

chrome/common/extensions/api/_features.md

Index: chrome/common/extensions/api/_features.md
diff --git a/chrome/common/extensions/api/_features.md b/chrome/common/extensions/api/_features.md
new file mode 100644
index 0000000000000000000000000000000000000000..adb58707be51efa3e3765fa3663ac5414f6b62a5
--- /dev/null
+++ b/chrome/common/extensions/api/_features.md
@@ -0,0 +1,261 @@
+# Extension Features Files
+
+[TOC]
+
+## Summary
+
+The Extension features files specify the different requirements for extension
+feature availability.
+
+An **extension feature** can be any component of extension capabilities. Most
+notably, this includes extension APIs, but there are also more structural or
+behavioral features, such as web accessible resources or event pages.
+
+## Files
+
+There are four different feature files used:
+[\_api\_features](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/_api_features.json):

[lazyboy, 2016/08/19 17:58:55]

Precede each files with "* " for bullets?

[Devlin, 2016/08/19 18:58:15]

Done.

+Specifies the requirements for API availability. If an extension doesn't satisfy
+the requirements, the API will not be accessible in the extension's code.
+[\_permission\_features](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/_permission_features.json):
+Specifies the requirements for permission availability. If an extension doesn't
+satisfy the requirements, the permission will not be granted and the extension
+will have an install warning.
+[\_manifest\_features](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/_manifest_features.json):
+Specifies the requirements for manifest entry availability. If an extension
+doesn't satisfy the requirements, the extension will fail to load with an error.
+[\_behavior\_features](https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/_behavior_features.json):
+Specifies the requirements for miscellaneous extension behaviors. This should
+typically not be used.
+
+Note that these files may be present under chrome/common/extensions/api, as well
+as under extensions/common/api and extensions/shell/common/api.
+
+## Grammar
+
+The feature files are written in JSON. Each file contains a single JSON object
+with properties for each feature.
+
+```
+{
+  "feature1": <definition>,
+  "feature2": <definition>,
+  ...
+}
+```
+
+### Simple and Complex Features
+
+Most features are known as "simple" features. These are features whose
+definition is a single object that contains the properties describing the
+criteria for availability. A simple feature might look like this:
+```
+"feature1": {
+  "dependencies": ["permission:feature1"],
+  "contexts": ["blessed_extension"]
+}
+```
+`feature1` has a single definition, which says for it to be available, a
+permission must be present and it must be executed from a blessed context.
+(These concepts are covered more later.)

[asargent_no_longer_on_chrome, 2016/08/19 19:33:16]

suggestion: "...are covered more later in this document"

[Devlin, 2016/08/19 21:00:57]

Done.

+
+Features can also be "complex". A complex feature has a list of objects to
+specify multiple groups of possible properties. A complex feature could look
+like this:
+```
+"feature1": [{
+  "dependencies": ["permission:feature1"],
+  "contexts": ["blessed_extension"]
+}, {
+  "dependencies": ["permission:otherPermission"],
+  "contexts": ["blessed_extension", "unblessed_extension"]
+}]
+```
+
+With complex features, if either of the definitions are matched, the feature

[asargent_no_longer_on_chrome, 2016/08/19 19:33:16]

suggestion: you might also say something like "they are logically OR'd together"

[Devlin, 2016/08/19 21:00:57]

I like it, done.

+is available. Complex features should frequently be avoided, as it makes the
+logic more involved and slower.
+
+### Inheritance
+
+By default, features inherit from parents. A feature's ancestry is specified by
+it's name, where a child feature is the parent's name followed by a '.' and the

[asargent_no_longer_on_chrome, 2016/08/19 19:33:16]

grammar nazi sez: "it's" -> "its"

[Devlin, 2016/08/19 21:00:57]

d'oh!  I catch this in reading, but never writing.  Thanks. :)

+child's name. That is, `feature1.child` is the child of `feature1`. Inheritance
+can carry for multiple levels (e.g. `feature1.child.child`), but this is rarely
+(if ever) useful.
+
+A child feature inherits all the properties of its parent, but can choose to
+override them or add additional properties. Take the example:
+```
+"feature1": {
+  "dependencies": ["permission:feature1"],
+  "contexts": ["blessed_extension"]
+},
+"feature1.child": {
+  "contexts": ["unblessed_extension"],
+  "extension_types": ["extension"]
+}
+```
+
+In this case, `feature1.child` will effective have the properties

[lazyboy, 2016/08/19 17:58:55]

"will effectively have the properties:"

[Devlin, 2016/08/19 18:58:15]

Done.

+```
+"dependencies": ["permission:feature1"], # inherited from feature1
+"contexts": ["unblessed_extension"],     # inherited value overridden by child
+"extension_types": ["extension]          # specified by child
+```
+
+If you don't want a child to inherit any features from the parent, add the
+property `"noparent": true`.

[asargent_no_longer_on_chrome, 2016/08/19 19:33:16]

It would be nice to add a sentence here with an example of why you'd want to
have a feature be a child of another but not inherit any features. 

[Devlin, 2016/08/19 21:00:57]

Done.

+
+If the parent of a feature is a complex feature, the feature system needs to
+know which parent to inherit from. To do this, add the property
+`"default_parent": true` to one of the feature definitions in the parent
+feature.
+
+## Properties
+
+The following properties are supported in the feature system.
+
+### blacklist
+
+The `blacklist` property specifies a list of ID hashes for extensions that

[lazyboy, 2016/08/19 17:58:55]

Add a todo to describe about how these hashes can be found? I definitely had
trouble figuring this out in the past.

[Devlin, 2016/08/19 18:58:15]

Added a note to see _api_features.json, since there's already the TODO at the
bottom to move more of the documentation in here.

+cannot access a feature.
+
+Accepted values are lists of id hashes.
+
+### channel
+
+The `channel` property specifies a maximum channel for the feature availability.
+That is, specifying `dev` means that the feature is available on `dev`,
+`canary`, and `trunk`.
+
+Accepted values are a single string from `trunk`, `canary`, `dev`, `beta`, and
+`stable`.
+
+### command\_line\_switch
+
+The `command_line_switch` property specifies a command line switch that must be

[lazyboy, 2016/08/19 17:58:55]

s/command line switch/command line switch (without --)

[Devlin, 2016/08/19 18:58:16]

Done, but put in the "accepted values" sentence.

+present for the feature to be available.
+
+Accepted values are a single string for the command line switch.
+
+### component\_extensions\_auto\_granted
+
+The `component_extensions_auto_granted` specifies whether or not component
+extensions should be automatically granted access to the feature. By default,
+this is `true`.
+
+The only accepted value is `false` (since true is the default).

[lazyboy, 2016/08/19 17:58:55]

not sure: The only accepted boolean value is..
to stress this is boolean and not string "false".

[Devlin, 2016/08/19 18:58:15]

sgtm.  Clarity never hurts.  (Though it would just be a compiler error if they
tried "false")

+
+### contexts
+
+The `contexts` property specifies which JavaScript contexts can access the
+feature. All API features must specify at least one context, and only API
+features can specify contexts.
+
+Accepted values are a list of strings from `blessed_extension`,

[lazyboy, 2016/08/19 17:58:55]

Contexts are fun stuff and also source of confusion. Add a todo to describe
these?

[Devlin, 2016/08/19 18:58:15]

Already done at the bottom. :)

+`blessed_web_page`, `content_script`, `extension_service_worker`,
+`web_page`, `webui`, and `unblessed_extension`.
+
+### default\_parent
+
+The `default_parent` property specifies a feature definition from a complex
+feature to be used as the parent for any children. See also Inheritance.
+
+The only accepted value is `true`.
+
+### dependencies
+
+The `dependencies` property specifies which other features must be present in
+order to access this feature. This is useful so that you don't have to
+re-specify all the same properties on an API feature and a permission feature.
+
+A common practice is to put as many restrictions as possible in the
+permission or manifest feature so that we warn at extension load, and put
+relatively limited properties in an API feature with a dependency on the
+manifest or permission feature.
+
+To specify a dependent feature, use the prefix the feature name with the type
+of feature it is, followed by a colon. For example, in order to specify a
+dependency on a permission feature `foo`, we would add the dependency entry
+`permission:foo`.
+
+Accepted values are lists of strings specifying the dependent features.
+
+### extension\_types
+
+The `extension_types` properties specifies the different classes of extensions
+that can use the feature.  It is very common for certain features to only be
+allowed in certain extension classes, rather than available to all types.
+
+Accepted values are lists of strings from `extension`, `hosted_app`,
+`legacy_packaged_app`, `platform_app`, `shared_module`, and `theme`.

[asargent_no_longer_on_chrome, 2016/08/19 19:33:16]

Possibly worth mentioning that "platform_app" means "non-legacy packaged app" in
terms of public documentation? (and that's the term which we use elsewhere in
the code for these)

[Devlin, 2016/08/19 21:00:57]

I've added a TODO for this. I'm still trying to figure out where best to put
some of the documentation like this, since I'm not sure we want to duplicate the
documentation in the code, so for some of these it may just become "See
Manifest::Type".

+
+### location
+
+The `location` property specifies the required install location of the
+extension.
+
+Accepted values are a single string from `component`, `external_component`, and
+`policy`.
+
+### internal
+
+The `internal` property specifies whether or not a feature is considered

[lazyboy, 2016/08/19 17:58:55]

This is not exposed to developers or something that expands the "internal" word
a bit.

[Devlin, 2016/08/19 18:58:15]

Done.

+internal to Chromium.
+
+The only accepted value is `true`.
+
+### matches
+
+The `matches` property specifies url patterns which should be allowed to access
+the feature. Only API features may specify `matches`, and `matches` only make
+sense with a context of either `webui` or `web_page`.
+
+Accepted values are a list of strings specifying the match patterns.
+
+### max\_manifest\_version
+
+The `max_manifest_version` property specifies the maximum manifest version to be
+allowed to access a feature. Extensions with a greater manifest version cannot
+access the feature.
+
+The only accepted value is `1`, as currently the highest possible manifest
+version is `2`.
+
+### min\_manifest\_version
+
+The `min_manifest_version` property specifies the minimum manifest version to be
+allowed to access a feature. Extensions with a lesser manifest version cannot
+access the feature.
+
+The only accepted value is `2`, as this is currently the highest possible
+manifest version.
+
+### noparent
+
+The `noparent` property specifies that a feature should not inherit any
+properties from a derived parent. See also Inheritance.
+
+The only accepted value is `true`.
+
+### platforms
+
+The `platforms` property specifies the properties the feature should be
+available on.
+
+The accepted values are lists of strings from `chromeos`, `mac`, `linux`, and
+`win`.
+
+### whitelist
+
+The `whitelist` property specifies a list of ID hashes for extensions that
+are the only extensions allowed to access a feature.
+
+Accepted values are lists of id hashes.
+
+## Still to come
+
+TODO(devlin): Move documentation for how to create ID hashes, possibly move

[lazyboy, 2016/08/19 17:58:55]

Ah, I notice this now, consolidate my comments above for TODO here too then.

[Devlin, 2016/08/19 18:58:16]

TODOs for hashes and contexts are already here, so I think we're set. :)

+documentation for feature contexts, and add documentation for the compilation
+process. Probably also more on requirements for individual features.