Please fix the genrule documentation!

Description of the problem / feature request:

It's way too hard to figure out how to use genrules for the trivial case of generating and depending on multiple c header files. I have a very simple cc_binary rule that needs headers generated by:

genrule(
    name = "mkhdrs",
    srcs = ["obazl.c","fs_utils.c"],
    outs = ["obazl.h","fs_utils.h"],
    cmd = "\n".join([
        "$(location :makeheaders) coq/*.c;",
        "cp coq/*.h $(@D)"
    ]),
    tools = [":makeheaders"]
)

By trial and error I discovered this works:

    copts = ["-I", "bazel-out/darwin-fastbuild/bin/coq"]

which is obviously a hack. After too much time searching the web, I found:

    copts = ["-I", "$(GENDIR)/coq"],

This is very obscure, but only because the documentation is so spare. At the least I recommend adding something like this to the "Examples" section of genrule

Feature requests: what underlying problem are you trying to solve with this feature?

Inadequate documentation.

Have you found anything relevant by searching the web?

Yes, but the point is this sort of base case should not require web searching.