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

### 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][concepts] 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][actions] is that `declare_directory` is for creating temporary/scratch directories whose lifetime is indeterminate after the rule's implementation function returns.

[concepts]: https://docs.bazel.build/versions/master/build-ref.html#label_directory
[actions]: https://docs.bazel.build/versions/master/skylark/lib/actions.html#declare_directory

### 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).

Start with the linked `declare_directory` documentation and the Concepts and Terminology page, then review the Bazel source-tree integration tests mentioned in the issue for established `TreeArtifact` behavior. Done means the documentation clearly explains when declared directories can be rule inputs, how their outputs persist, and how `TreeArtifact` semantics should be understood.

Written by the indexing model from the issue text.