Add docstrings/comments to the examples

rules/actions_run/execute.bzl

@@ -1,3 +1,13 @@
+"""Execute a binary.
+
+The example below executes the binary target "//actions_run:merge" with
+some arguments. The binary will be automatically built by Bazel.
+
+The rule must declare its dependencies. To do that, we pass the target to
+the attribute "_merge_tool". Since it starts with an underscore, it is private
+and users cannot redefine it.
+"""
+
 def _impl(ctx):
   # The list of arguments we pass to the script.
   args = [ctx.outputs.out.path] + [f.path for f in ctx.files.chunks]

rules/actions_write/file.bzl

@@ -1,3 +1,10 @@
+"""Generate a file.
+
+In this example, the content is passed via an attribute. If you generate
+large files with a lot of static content, consider using
+`ctx.actions.expand_template` instead.
+"""
+
 def _impl(ctx):
   output = ctx.outputs.out
   ctx.actions.write(output=output, content=ctx.attr.content)

rules/depsets/foo.bzl

@@ -1,5 +1,4 @@
-# A provider with one field, transitive_sources.
-FooFiles = provider()
+FooFiles = provider("transitive_sources")
 
 def get_transitive_srcs(srcs, deps):
   """Obtain the source files for a target and its transitive dependencies.

rules/expand_template/hello.bzl

@@ -1,3 +1,9 @@
+"""Generate a file using a template.
+
+It is much more memory-efficient to use a template file than creating the whole
+content during the analysis phase.
+"""
+
 # Label of the template file to use.
 _TEMPLATE = "//expand_template:hello.cc"
 

rules/shell_command/size.bzl

@@ -1,3 +1,11 @@
+"""Execute a shell command.
+
+While convenient, Shell commands should be used carefully. Generating the
+command-line can lead to escaping and injection issues. It can also create
+portability problems. It is often better to declare a binary target in a
+BUILD file and execute it.
+"""
+
 def _impl(ctx):
   output = ctx.outputs.out
   input = ctx.file.file
@@ -6,7 +14,7 @@ def _impl(ctx):
       inputs=[input],
       outputs=[output],
       progress_message="Getting size of %s" % input.short_path,
-      command="stat -L -c%%s %s > %s" % (input.path, output.path))
+      command="stat -L -c%%s '%s' > '%s'" % (input.path, output.path))
 
 size = rule(
     implementation=_impl,