Revamp rules.md documentation for files

Unified "Files" and "Output files" sections. Renamed "declared files" to "predeclared files" to avoid confusion with "declare_file()"/"declare_directory()".

RELNOTES: None
PiperOrigin-RevId: 187017607

2 files changed, 19 insertions, 18 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
index 85873b27a0..918c6b998c 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java
@@ -101,16 +101,14 @@ import javax.annotation.Nullable;
  */
 @Immutable
 @SkylarkModule(
-  name = "File",
-  category = SkylarkModuleCategory.BUILTIN,
-  doc =
-      "<p>This type represents a file or directory used by the build system. It can be "
-          + "either a source file or a derived file produced by a rule.</p>"
-          + "<p>The File constructor is private, so you cannot call it directly to create new "
-          + "Files. You typically get a File object from a "
-          + "<a href='Target.html'>Target</a>, or using "
-          + "<a href='actions.html#declare_file'>ctx.actions.declare_file</a>, "
-          + "or <a href='actions.html#declare_directory'>ctx.actions.declare_directory</a>."
+    name = "File",
+    category = SkylarkModuleCategory.BUILTIN,
+    doc = "This object is created during the analysis phase to represent a file or directory that "
+        + "will be read or written during the execution phase. It is not an open file handle, and "
+        + "cannot be used to directly read or write file contents. Rather, you use it to construct "
+        + "the action graph in a rule implementation function by passing it to action-creating "
+        + "functions. See the <a href='../rules.$DOC_EXT#files'>Rules page</a> for more "
+        + "information."
 )
 @AutoCodec
 public class Artifact
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java
index d991f493f4..e14bfc0046 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkActionFactory.java
@@ -103,14 +103,17 @@ public class SkylarkActionFactory implements SkylarkValue {
   @SkylarkCallable(
     name = "declare_file",
     doc =
-        "Declares that rule or aspect creates a file with the given filename. "
-            + "If <code>sibling</code> is not specified, file name is relative to "
-            + "package directory, otherwise the file is in the same directory as "
-            + "<code>sibling</code>. "
-            + "You must create an action that generates the file. <br>"
-            + "Files cannot be created outside of the current package. "
-            + "Files that are specified in rule's outputs do not need to be declared and are "
-            + "available through <a href=\"ctx.html#outputs\"><code>ctx.outputs</code></a>. "
+        "Declares that the rule or aspect creates a file with the given filename. "
+            + "If <code>sibling</code> is not specified, the file name is relative to the package"
+            + "directory, otherwise the file is in the same directory as <code>sibling</code>."
+            + "Files cannot be created outside of the current package."
+            + "<p>Remember that in addition to declaring a file, you must separately create an "
+            + "action that emits the file. Creating that action will require passing the returned "
+            + "<code>File</code> object to the action's construction function."
+            + "<p>Note that <a href='../rules.$DOC_EXT#files'>predeclared output files</a> do not "
+            + "need to be (and cannot be) declared using this function. You can obtain their "
+            + "<code>File</code> objects from <a href=\"ctx.html#outputs\"><code>ctx.outputs</code>"
+            + "</a> instead. "
             + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
             + "computed_dependencies/hash.bzl\">See example of use</a>",
     parameters = {