Transitions documentation: de-experimentalize, add example

PiperOrigin-RevId: 274264576

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",