Adding documentation for initializing blink features

- New doc explaining how to initialize blink features
  in content layer
- Update feature flag guides to point to the new doc

Bug: 832393
Change-Id: Id0cd47a2b926c55e15516242cbf6382e199b1537
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1873991
Reviewed-by: Jason Chase <chasej@chromium.org>
Commit-Queue: Rodney Ding <rodneyding@google.com>
Cr-Commit-Position: refs/heads/master@{#711828}

docs/how_to_add_your_feature_flag.md

@@ -14,7 +14,7 @@ For example, if you want to use the flag in src/content, you should add a base::
 If you want to use the flag in blink, you should also read
 [Runtime Enable Features](https://www.chromium.org/blink/runtime-enabled-features).
 
-You can refer to [this CL](https://chromium-review.googlesource.com/c/554510/)
+You can refer to [this CL](https://chromium-review.googlesource.com/c/554510/) and [this document](https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/InitializeBlinkFeatures.md)
 to see
 
 1. where to add the base::Feature
@@ -22,11 +22,7 @@ to see
 [[2](https://chromium-review.googlesource.com/c/554510/8/content/public/common/content_features.h)]
 2. how to use it
 [[1](https://chromium-review.googlesource.com/c/554510/8/content/common/service_worker/service_worker_utils.cc#153)]
-3. how to wire the base::Feature to WebRuntimeFeatures
-[[1](https://chromium-review.googlesource.com/c/554510/8/content/child/runtime_features.cc)]
-[[2](https://chromium-review.googlesource.com/c/554510/8/third_party/blink/public/platform/web_runtime_features.h)]
-[[3](https://chromium-review.googlesource.com/c/554510/third_party/blink/Source/platform/exported/web_runtime_features.cc)]
-[[4](https://chromium-review.googlesource.com/c/554510/8/third_party/blink/renderer/platform/runtime_enabled_features.json5)]
+3. how to wire your new base::Feature to a blink runtime feature[[1](https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/InitializeBlinkFeatures.md)]
 4. how to use it in blink
 [[1](https://chromium-review.googlesource.com/c/554510/8/third_party/blnk/renderere/core/workers/worker_thread.cc)]
 

docs/initialize_blink_features.md

@@ -0,0 +1,80 @@
+# Initialization of Blink runtime features in content layer
+This document outlines how to initialize your Blink runtime features in the
+Chromium content layer, more specifically in
+[content/child/runtime_features.cc][runtime_features]. To learn more on how to
+set up features in blink, see
+[Runtime Enabled Features][RuntimeEnabledFeatures].
+
+## Step 1: Do you need a custom Blink feature enabler function?
+If you simply need to enable/disable the Blink feature you can simply use
+[WebRuntimeFeatures::EnableFeatureFromString()][EnableFeatureFromString].
+
+However, if there are side effects (e.g. you need to disable other features if
+this feature is also disabled), you should declare a custom enabler function in
+- [third_party/blink/public/platform/web_runtime_features.h][WebRuntimeFeatures.h]
+- [third_party/blink/public/platform/web_runtime_features.cc][WebRuntimeFeatures.cc]
+
+## Step 2: Determine how your feature is initialized.
+### 1) Depends on OS-specific Macros:
+Add your code for controlling the Blink feature in
+[SetRuntimeFeatureDefaultsForPlatform()][SetRuntimeFeatureDefaultsForPlatform]
+using the appropriate OS macros.
+### 2) Depends on the status of a base::Feature:
+Add your code to the function
+[SetRuntimeFeaturesFromChromiumFeatures()][SetRuntimeFeaturesFromChromiumFeatures].
+
+If your Blink feature has a custom enabler function, add a new entry to
+`blinkFeatureToBaseFeatureMapping`. For example, a new entry like this:
+```
+{wf::EnableNewFeatureX, features::kNewFeatureX, kEnableOnly},
+```
+will call `wf::EnableNewFeatureX` to enable it only if `features::kNewFeatureX`
+is enabled.
+
+If your Blink feature does not have a custom enabler function, you need to add
+the entry to `runtimeFeatureNameToChromiumFeatureMapping`. For example, a new
+entry like this:
+```
+{"NewFeatureY", features::kNewFeatureY, kUseFeatureState},
+```
+will call `wf::EnableFeatureFromString` with your feature name to set it to
+whichever state your `features::kNewFeatureY` is in.
+
+For more detailed explanation on the options you have, read the comment in enum
+[RuntimeFeatureEnableOptions][EnableOptions].
+### 3) Set by a command line switch to enable or disable:
+Add your code to the function
+[SetRuntimeFeaturesFromCommandLine()][SetRuntimeFeaturesFromCommandLine].
+
+If your Blink feature has a custom enabler function, add a new entry to
+`switchToFeatureMapping`. For example, a new entry like this:
+```
+{wrf::EnableNewFeatureX, switches::kNewFeatureX, false},
+```
+will call `wf::EnableNewFeatureX` to disable it only if that
+`switches::kNewFeatureX` exists on the command line.
+
+### 4) Controlled by parameters from a field trial:
+Add your code to the function
+[SetRuntimeFeaturesFromFieldTrialParams()][SetRuntimeFeaturesFromFieldTrialParams].
+
+### 5) Combination of the previous options or not covered:
+For example, you Blink feature could be controlled by both a base::Feature and a
+command line switch. In this case, your custom logic should live here in
+[`SetCustomizedRuntimeFeaturesFromCombinedArgs()`][SetCustomizedRuntimeFeaturesFromCombinedArgs].
+
+
+[EnableOptions]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#135>
+[runtime_features]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc>
+[RuntimeEnabledFeatures]:
+<https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/RuntimeEnabledFeatures.md>
+[WebRuntimeFeatures.h]:
+<https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/exported/web_runtime_features.h>
+[WebRuntimeFeatures.cc]:
+<https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/exported/web_runtime_features.cc>
+[EnableFeatureFromString]:<https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/public/platform/web_runtime_features.h#56>
+[SetRuntimeFeatureDefaultsForPlatform]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#46>
+[SetCustomizedRuntimeFeaturesFromCombinedArgs]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#487>
+[SetRuntimeFeaturesFromChromiumFeatures]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#160>
+[SetRuntimeFeaturesFromCommandLine]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#390>
+[SetRuntimeFeaturesFromFieldTrialParams]:<https://chromium.googlesource.com/chromium/src/+/HEAD/content/child/runtime_features.cc#448>