Add some docs on what rules and files are
--
MOS_MIGRATED_REVID=125449364
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 b3b8682..fe03f57 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
@@ -91,8 +91,14 @@
*/
@Immutable
@SkylarkModule(name = "File",
- doc = "This type represents a file used by the build system. It can be "
- + "either a source file or a derived file produced by a rule.")
+ doc = "<p>This type represents a file 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. If you have a Skylark rule that needs to create a new File, you might need to "
+ + "add the label to the attrs (if it's an input) or the outputs (if it's an output). Then "
+ + "you can access the File through the rule's <a href='ctx.html'>context</a>. You can "
+ + "also use <a href='ctx.html#new_file'>ctx.new_file</a> to create a new file in the rule "
+ + "implementation.</p>")
public class Artifact
implements FileType.HasFilename, ActionInput, SkylarkValue, Comparable<Object> {
