Improve the documentation for ctx.actions.symlink.

This API does two different things and users occasionally get confused by it (see e.g. #16070). In particular, it is crucial to understand whether Bazel tracks the symlink on its own or the contents of its target.

PiperOrigin-RevId: 483604065
Change-Id: Iab14c264eb320cd324b64b3af2a400df948dbf3c

src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkActionFactoryApi.java

@@ -163,19 +163,21 @@ public interface StarlarkActionFactoryApi extends StarlarkValue {
   @StarlarkMethod(
       name = "symlink",
       doc =
-          "Creates an action that writes a symlink in the file system."
-              + "<p>This function must be called with exactly one of <code>target_file</code> or "
-              + "<code>target_path</code> specified.</p>"
-              + "<p>If <code>target_file</code> is used, then <code>output</code> must be declared "
-              + "by <a href=\"#declare_file\"><code>declare_file()</code></a> or "
-              + "<a href=\"#declare_directory\"><code>declare_directory()</code></a> and match the "
-              + "type of <code>target_file</code>. In this case, <code>output</code> will be a "
-              + "symlink whose contents are the path of <code>target_file</code>.</p>"
-              + "<p>Otherwise, if <code>target_path</code> is used, then <code>output</code> must "
-              + "be declared with "
-              + "<a href=\"#declare_symlink\"><code>declare_symlink()</code></a>). In this case, "
-              + "<code>output</code> will be a symlink whose contents are <code>target_path</code>."
-              + "This can be used to create a dangling symlink.</p>",
+          "Creates an action that writes a symlink in the file system.<p>This function must be"
+              + " called with exactly one of <code>target_file</code> or <code>target_path</code>"
+              + " specified.</p><p>When you use <code>target_file</code>, declare"
+              + " <code>output</code> with <a"
+              + " href=\"#declare_file\"><code>declare_file()</code></a> or <a"
+              + " href=\"#declare_directory\"><code>declare_directory()</code></a> and match the"
+              + " type of <code>target_file</code>. This makes the symlink point to"
+              + " <code>target_file</code>. Bazel invalidates the output of this action whenever"
+              + " the target of the symlink or its contents change.</p><p>Otherwise, when you use"
+              + " <code>target_path</code>, declare <code>output</code> with <a"
+              + " href=\"#declare_symlink\"><code>declare_symlink()</code></a>). In this case, the"
+              + " symlink points to <code>target_path</code>. Bazel never resolves the symlink"
+              + " and the output of this action is invalidated only when the text contents of the"
+              + " symlink (that is, the value of <code>readlink()</code>) changes. In particular,"
+              + " this can be used to create a dangling symlink.</p>",
       parameters = {
         @Param(
             name = "output",