Bazel: Document `ctx.actions.declare_directory` and `TreeArtifact` semantics

[beasleyr-vmw]

Description of the problem / feature request:

ctx.actions.declare_directory semantics are unclear. The method's documentation could use improvement.

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

This is based on code review discussions at work.

Users who first Concepts and Terminology get the impression that they cannot use directories as rule inputs under any circumstance, or that, at best, doing so relies on undefined behavior. They are then surprised when I begin publishing code review requests with changes which export action outputs via ctx.actions.declare_directory. Their interpretation of the declare_directory documentation is that declare_directory is for creating temporary/scratch directories whose lifetime is indeterminate after the rule's implementation function returns.

Have you found anything relevant by searching the web?

I've found (and pointed my colleagues to) informal discussions about declare_directory and TreeArtifacts as well as links to Bazel's source tree (particularly integration tests).

[beasleyr-vmw]

Also worth pointing out the following blurb from https://docs.bazel.build/versions/master/skylark/rules.html#actions:

If an action generates an unknown number of outputs and you want to keep them all, you must group them in a single file (e.g., a zip, tar, or other archive format). This way, you will be able to deterministically declare your outputs.

AFAIK declared directories / TreeArtifacts are a suitable alternative to packing everything into a single archive (as alluded to elsewhere, like https://github.com/bazelbuild/bazel/issues/2414#issuecomment-383841229), so this could (should?) also be revised.

[Globegitter]

As a note, we use directories as well as declare_directory all over the pace internally. And we have not have had problems, declaring them as outputs, then as inputs to other rules as well as referencing directories in file groups.