Improve the documentation for ctx.actions.symlink.
This API does two different things and users occasionally get confused by it (see e.g. https://github.com/bazelbuild/bazel/issues/16070). In particular, it is crucial to understand whether Bazel tracks the symlink on its own or the contents of its target.
@@ -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",
