From c731933e93c19b5e70275e4f4ae2e7da90fa3a32 Mon Sep 17 00:00:00 2001
From: gregce <gregce@google.com>
Date: Fri, 11 Oct 2019 15:45:20 -0700
Subject: [PATCH] Transitions documentation: de-experimentalize, add example

PiperOrigin-RevId: 274264576
---
 .../config/ConfigGlobalLibraryApi.java        | 23 +++++++++++++++----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigGlobalLibraryApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigGlobalLibraryApi.java
index b863227ef938d5..b43e3a1cb5cca1 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigGlobalLibraryApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/config/ConfigGlobalLibraryApi.java
@@ -34,12 +34,25 @@
 public interface ConfigGlobalLibraryApi {
   @SkylarkCallable(
       name = "transition",
-      // TODO(cparsons): Improve documentation with an example once this feature is
-      // non-experimental.
       doc =
-          "<b>Experimental. This type is experimental and subject to change at any time. Do "
-              + "not depend on it.</b><p> Creates a configuration transition to be applied across"
-              + " a dependency edge.",
+          "A transition that reads a set of input build settings and writes a set of output build "
+              + "settings."
+              + "<p>Example:</p>"
+              + "<p><pre class=\"language-python\">\n"
+              + "def _transition_impl(settings, attr):\n"
+              + "    # This transition just reads the current CPU value as a demonstration.\n"
+              + "    # A real transition could incorporate this into its followup logic.\n"
+              + "    current_cpu = settings[\"//command_line_option:cpu\"]\n"
+              + "    return {\"//command_line_option:compilation_mode\": \"dbg\"}\n"
+              + "\n"
+              + "build_in_debug_mode = transition(\n"
+              + "    implementation = _transition_impl,\n"
+              + "    inputs = [\"//command_line_option:cpu\"],\n"
+              + "    outputs = [\"//command_line_option:compilation_mode\"],\n"
+              + ")"
+              + "</pre></p>"
+              + "<p>For more details see <a href=\"../config.html#user-defined-transitions\">"
+              + "here</a>.</p>",
       parameters = {
         @Param(
             name = "implementation",