Improve the stardoc pipeline

doc_build/BUILD

@@ -53,9 +53,9 @@ ORDER = [
     ("license",         "//rules:license.bzl"),
     ("_license",        "//rules:license.bzl"),
     ("license_kind",    "//rules:license_kind.bzl"),
-    ("_license_kind",   "//rules:license_kind.bzl"),
+    ("license_kind_internal",   "//rules:license_kind.bzl"),
     ("package_info",    "//rules:package_info.bzl"),
-    ("_package_info",   "//rules:package_info.bzl"),
+    ("package_info_internal",   "//rules:package_info.bzl"),
     ("LicenseInfo",     "//rules:providers.bzl"),
     ("LicenseKindInfo", "//rules:providers.bzl"),
     ("PackageInfo",     "//rules:providers.bzl"),

rules/license.bzl

@@ -11,9 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Rules for declaring the compliance licenses used by a package.
-
-"""
+"""Rule for declaring the OSS licenses used by a package."""
 
 load(
     "@rules_license//rules:providers.bzl",
@@ -87,14 +85,15 @@ def license(
         visibility = ["//visibility:public"]):
     """Wrapper for license rule.
 
-    @wraps(_license)
-
     Args:
       name: str target name.
       license_text: str Filename of the license file
-      license_kind: label a single license_kind. Only one of license_kind or license_kinds may
-                    be specified
-      license_kinds: list(label) list of license_kind targets.
+      license_kind: label Legacy attribute to specify a single license_kind.
+          See license_kinds.
+      license_kinds: list(label) License kind(s) of this license.
+          If multiple license kinds are listed in the LICENSE file, and they
+          all apply, then all of them should be listed here. If the user can
+          choose a single one of many, then only list one here.
       copyright_notice: str Copyright notice associated with this package.
       package_name: str A human readable name identifying this package. This
                     may be used to produce an index of OSS packages used by

rules/license_kind.bzl

@@ -11,7 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Proof of concept. License restriction."""
 
 load("@rules_license//rules:providers.bzl", "LicenseKindInfo")
 
@@ -21,7 +20,7 @@ load("@rules_license//rules:providers.bzl", "LicenseKindInfo")
 # that it may user privately.
 #
 
-def _license_kind_impl(ctx):
+def _license_kind_internal_impl(ctx):
     provider = LicenseKindInfo(
         name = ctx.attr.name,
         label = "@%s//%s:%s" % (
@@ -34,8 +33,8 @@ def _license_kind_impl(ctx):
     )
     return [provider]
 
-_license_kind = rule(
-    implementation = _license_kind_impl,
+license_kind_internal = rule(
+    implementation = _license_kind_internal_impl,
     attrs = {
         "conditions": attr.string_list(
             doc = "Conditions to be met when using software under this license." +
@@ -54,13 +53,13 @@ _license_kind = rule(
 def license_kind(name, **kwargs):
     """Wrapper for license_kind.
 
-    @wraps(_license_kind)
+    @wraps(license_kind_internal)
     """
     if "conditions" not in kwargs:
         kwargs["conditions"] = []
     if "long_name" not in kwargs:
         kwargs["long_name"] = name
-    _license_kind(
+    license_kind_internal(
         name = name,
         applicable_licenses = [],
         **kwargs

rules/package_info.bzl

@@ -23,7 +23,7 @@ load(
 # package_info()
 #
 
-def _package_info_impl(ctx):
+def _package_info_internal_impl(ctx):
     provider = PackageInfo(
         # Metadata providers must include a type discriminator. We don't need it
         # to collect the providers, but we do need it to write the JSON. We
@@ -50,8 +50,8 @@ def _package_info_impl(ctx):
     )
     return [provider, generic_provider]
 
-_package_info = rule(
-    implementation = _package_info_impl,
+package_info_internal = rule(
+    implementation = _package_info_internal_impl,
     attrs = {
         "package_name": attr.string(
             doc = "A human readable name identifying this package." +
@@ -87,7 +87,7 @@ def package_info(
         **kwargs):
     """Wrapper for package_info rule.
 
-    @wraps(_package_info)
+    @wraps(package_info_internal)
 
     The purl attribute should be a valid pURL, as defined in the
     [pURL spec](https://github.com/package-url/purl-spec).
@@ -105,7 +105,7 @@ def package_info(
       kwargs: other args. Most are ignored.
     """
     visibility = kwargs.get("visibility") or ["//visibility:public"]
-    _package_info(
+    package_info_internal(
         name = name,
         package_name = package_name,
         package_url = package_url,

rules/providers.bzl

@@ -11,12 +11,12 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Basic providers for license rules.
 
-This file should only contain the basic providers needed to create
-license and package_info declarations. Providers needed to gather
-them are declared in other places.
-"""
+"""Core providers for license rules."""
+
+# This file should only contain the basic providers needed to create
+# license and package_info declarations. Providers needed to gather
+# them are declared in other places.
 
 load(
     "@rules_license//rules_gathering:gathering_providers.bzl",