Add more links to examples in the documentation.

RELNOTES: None.
PiperOrigin-RevId: 178946746

4 files changed, 30 insertions, 23 deletions

diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md
index 439568c5d7..80b8981251 100644
--- a/site/docs/skylark/concepts.md
+++ b/site/docs/skylark/concepts.md
@@ -38,7 +38,7 @@ example is perfectly legal (please note when to use quotation marks).
 load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
 ```
 
-In a `.bzl` file, symbols starting with `_` are private and cannot be loaded
+In a `.bzl` file, symbols starting with `_` are not exported and cannot be loaded
 from another file. Visibility doesn't affect loading (yet): you don't need to
 use `exports_files` to make a `.bzl` file visible.
 
diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index d9a3e40647..df28b8d08b 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -33,8 +33,7 @@ function to create a new rule and store it in a global variable:
 my_rule = rule(...)
 ```
 
-See [the cookbook](cookbook.md#empty) for examples. The rule can then be
-loaded by BUILD files:
+The rule can then be loaded in `BUILD` files:
 
 ```python
 load('//some/pkg:whatever.bzl', 'my_rule')
@@ -51,6 +50,8 @@ function decides what the outputs of the rule are and how to build them (using
 no external command can be executed. Instead, actions are registered and
 will be run in the execution phase, if their output is needed for the build.
 
+[See example](https://github.com/bazelbuild/examples/tree/master/rules/empty).
+
 ## Attributes
 
 An attribute is a rule argument, such as `srcs` or `deps`. You must list
@@ -81,11 +82,9 @@ See [an example](cookbook.md#attr) of using `attr` in a rule.
 
 ### <a name="private-attributes"></a> Private Attributes
 
-In Python, we use one leading underscore(`_`) for non-public methods and
-instance variables (see [PEP-8][1]).
-
-Similarly, if an attribute name starts with `_` it is private and users cannot
-set it.
+In Skylark, functions starting with a leading underscore (`_`) are not exported.
+Similarly, when an attribute name starts with `_`, the attribute is private and
+users of the rule cannot set it.
 It is useful in particular for label attributes (your rule will have an
 implicit dependency on this label).
 
@@ -226,6 +225,7 @@ An "implicit output" is a declared output that is not in the default outputs. In
 other words, it is not generated by default. Users can refer to its label to
 build the file explicitly. Use the `files` mentioned above if you need implicit
 outputs (like `_deploy.jar` files generated by `java_binary`).
+[See example](https://github.com/bazelbuild/examples/blob/master/rules/implicit_output/hash.bzl)
 
 ## Actions
 
@@ -621,5 +621,3 @@ _example_test = rule(
  ...
 )
 ```
-
-[1]: https://www.python.org/dev/peps/pep-0008/#id46
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 1bb4701ada..687dd08d0e 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
@@ -70,15 +70,14 @@ import java.util.Map;
 import java.util.UUID;
 import javax.annotation.Nullable;
 
-/**
- * Provides a Skylark interface for all action creation needs.
- */
+/** Provides a Skylark interface for all action creation needs. */
 @SkylarkModule(
-    name = "actions",
-    category = SkylarkModuleCategory.BUILTIN,
-    doc = "Module providing functions to create actions."
+  name = "actions",
+  category = SkylarkModuleCategory.BUILTIN,
+  doc =
+      "Module providing functions to create actions. "
+          + "Access this module using <a href=\"ctx.html#actions\">ctx.actions</a>."
 )
-
 public class SkylarkActionFactory implements SkylarkValue {
   private final SkylarkRuleContext context;
   private final SkylarkSemantics skylarkSemantics;
@@ -111,7 +110,9 @@ public class SkylarkActionFactory implements SkylarkValue {
             + "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\">ctx.outputs</a>.",
+            + "available through <a href=\"ctx.html#outputs\">ctx.outputs</a>. "
+            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+            + "computed_dependencies/hash.bzl\">See example of use</a>",
     parameters = {
       @Param(
         name = "filename",
@@ -238,7 +239,7 @@ public class SkylarkActionFactory implements SkylarkValue {
             + "to a file. This is used to generate files using information available in the "
             + "analysis phase. If the file is large and with a lot of static content, consider "
             + "using <a href=\"#expand_template\">expand_template</a>. "
-            + "<a href=\"https://github.com/laurentlb/examples/blob/master/rules/executable/executable.bzl\">"
+            + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/executable/executable.bzl\">"
             + "See example of use</a>",
     parameters = {
       @Param(name = "output", type = Artifact.class, doc = "the output file.", named = true),
@@ -283,7 +284,10 @@ public class SkylarkActionFactory implements SkylarkValue {
 
   @SkylarkCallable(
     name = "run",
-    doc = "Creates an action that runs an executable.",
+    doc =
+        "Creates an action that runs an executable. "
+            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+            + "actions_run/execute.bzl\">See example of use</a>",
     parameters = {
       @Param(
         name = "outputs",
@@ -455,7 +459,10 @@ public class SkylarkActionFactory implements SkylarkValue {
 
   @SkylarkCallable(
     name = "run_shell",
-    doc = "Creates an action that runs a shell command.",
+    doc =
+        "Creates an action that runs a shell command. "
+            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+            + "shell_command/size.bzl\">See example of use</a>",
     parameters = {
       @Param(
         name = "outputs",
@@ -773,7 +780,7 @@ public class SkylarkActionFactory implements SkylarkValue {
             + "dictionary appears in the template, it is replaced with the associated value. "
             + "There is no special syntax for the keys. You may for example use curly braces "
             + "to avoid conflicts (e.g. <code>{KEY}</code>). "
-            + "<a href=\"https://github.com/laurentlb/examples/blob/master/rules/expand_template/hello.bzl\">"
+            + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/expand_template/hello.bzl\">"
             + "See example of use</a>",
     parameters = {
       @Param(
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java
index 1dea86cf91..a2a02cc0b9 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkAttr.java
@@ -75,7 +75,9 @@ import javax.annotation.Nullable;
   doc =
       "Module for creating new attributes. "
           + "They are only for use with <a href=\"globals.html#rule\">rule</a> or "
-          + "<a href=\"globals.html#aspect\">aspect</a>."
+          + "<a href=\"globals.html#aspect\">aspect</a>. "
+          + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+          + "attributes/printer.bzl\">See example of use</a>."
 )
 public final class SkylarkAttr implements SkylarkValue {