Reword "package" documentation
This explains that while it is usually not right to specify a package
name with `//` prepended, that there are some cases where it makes
sense for understanding.
@@ -55,15 +55,25 @@ this file is in the `my/app/main/testdata` subdirectory of the repository:
//my/app/main:testdata/input.txt
```
-Don't confuse labels like `//my/app` with package names. Labels _always_ start
-with a repository identifier (often abbreviated `//`), but package names never
-do. Thus, `my/app` is the package containing `//my/app/lib` (which can also be
-written as `//my/app/lib:lib`).
-
-A common misconception is that `//my/app` refers to a package, or to _all_ the
-targets in a package; neither is true. Remember, it is equivalent to
-`//my/app:app`, so it names the `app` target in the `my/app` package of the
-current repository).
+Strings like `//my/app` and `@some_repo//my/app` have two meanings depending on
+the context in which they are used: when Bazel expects a label, they mean
+`//my/app:app` and `@some_repo//my/app:app`, respectively. But, when Bazel
+expects a package (e.g. in `package_group` specifications), they reference the
+package that contains that label.
+
+A common mistake in `BUILD` files is using `//my/app` to refer to a package, or
+to *all* the targets in a package--it does not. Remember, it is
+equivalent to `//my/app:app`, so it names the `app` target in the `my/app`
+package of the current repository.
+
+However, the use of `//my/app` to refer to a package is encouraged in the
+specification of a `package_group` or in `.bzl` files, because it clearly
+communicates that the package name is absolute and rooted in the top-level
+directory of the workspace.Strings like `//my/app` and `@some_repo//my/app` have
+two meanings depending on the context in which they are used: when Bazel expects
+a label, they mean `//my/app:app` and `@some_repo//my/app:app`,
+respectively. But, when Bazel expects a package (e.g. in `package_group`
+specifications), they reference the package that contains that label.
Relative labels cannot be used to refer to targets in other packages; the
repository identifier and package name must always be specified in this case.
