docs(bazel): add skydoc generation (#23544)

PR Close #23544

packages/bazel/src/ng_module.bzl

@@ -2,7 +2,7 @@
 #
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
-"""Implementation of the ng_module rule.
+"""Run Angular's AOT template compiler
 """
 
 load(":rules_typescript.bzl",
@@ -453,13 +453,21 @@ def _ng_module_impl(ctx):
 NG_MODULE_ATTRIBUTES = {
     "srcs": attr.label_list(allow_files = [".ts"]),
 
-    "deps": attr.label_list(aspects = DEPS_ASPECTS + [_collect_summaries_aspect]),
+    # Note: DEPS_ASPECTS is already a list, we add the cast to workaround
+    # https://github.com/bazelbuild/skydoc/issues/21
+    "deps": attr.label_list(
+        doc = "Targets that are imported by this target",
+        aspects = list(DEPS_ASPECTS) + [_collect_summaries_aspect]
+    ),
 
-    "assets": attr.label_list(allow_files = [
-      ".css",
-      # TODO(alexeagle): change this to ".ng.html" when usages updated
-      ".html",
-    ]),
+    "assets": attr.label_list(
+        doc = ".html and .css files needed by the Angular compiler",
+        allow_files = [
+            ".css",
+            # TODO(alexeagle): change this to ".ng.html" when usages updated
+            ".html",
+        ],
+    ),
 
     "factories": attr.label_list(
         allow_files = [".ts", ".html"],
@@ -515,7 +523,13 @@ ng_module = rule(
     attrs = NG_MODULE_RULE_ATTRS,
     outputs = COMMON_OUTPUTS,
 )
+"""
+Run the Angular AOT template compiler.
 
+This rule extends the [ts_library] rule.
+
+[ts_library]: http://tsetse.info/api/build_defs.html#ts_library
+"""
 
 # TODO(alxhub): this rule causes legacy ngc to produce Ivy outputs from global analysis information.
 # It exists to facilitate testing of the Ivy runtime until ngtsc is mature enough to be used

packages/bazel/src/ng_package/ng_package.bzl

@@ -2,7 +2,15 @@
 #
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
-"""Implementation of the ng_package rule.
+"""Package Angular libraries for npm distribution
+
+If all users of an Angular library use Bazel (e.g. internal usage in your company)
+then you should simply add your library to the `deps` of the consuming application.
+
+These rules exist for compatibility with non-Bazel consumers of your library.
+
+It packages your library following the Angular Package Format, see the
+specification of this format at https://goo.gl/jB3GVv
 """
 
 load("@build_bazel_rules_nodejs//:internal/collect_es6_sources.bzl", "collect_es6_sources")
@@ -352,6 +360,18 @@ NG_PACKAGE_ATTRS = dict(NPM_PACKAGE_ATTRS, **dict(ROLLUP_ATTRS, **{
 # some/path/to/my/package/index.js
 # we assume the files should be named "package.*.js"
 def primary_entry_point_name(name, entry_point, entry_point_name):
+  """This is not a public API.
+
+  Compute the name of the primary entry point in the library.
+
+  Args:
+    name: the name of the `ng_package` rule, as a fallback.
+    entry_point: The starting point of the application, see rollup_bundle.
+    entry_point_name: if set, this is the returned value.
+
+  Returns:
+    name of the entry point, which will appear in the name of generated bundles
+  """
   if entry_point_name:
       # If an explicit entry_point_name is given, use that.
       return entry_point_name
@@ -364,6 +384,19 @@ def primary_entry_point_name(name, entry_point, entry_point_name):
       return name
 
 def ng_package_outputs(name, entry_point, entry_point_name):
+  """This is not a public API.
+
+  This function computes the named outputs for an ng_package rule.
+
+  Args:
+    name: value of the name attribute
+    entry_point: value of the entry_point attribute
+    entry_point_name: value of the entry_point_name attribute
+
+  Returns:
+    dict of named outputs of the rule
+  """
+
   basename = primary_entry_point_name(name, entry_point, entry_point_name)
   outputs = {
       "fesm5": "fesm5/%s.js" % basename,
@@ -384,3 +417,6 @@ ng_package = rule(
     attrs = NG_PACKAGE_ATTRS,
     outputs = ng_package_outputs,
 )
+"""
+ng_package produces an npm-ready package from an Angular library.
+"""

packages/bazel/src/ng_rollup_bundle.bzl

@@ -3,11 +3,15 @@
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
 
-"""This provides a variant of rollup_bundle that works better for Angular apps.
+"""Rollup with Build Optimizer
 
-   It registers @angular-devkit/build-optimizer as a rollup plugin, to get
+   This provides a variant of the [rollup_bundle] rule that works better for Angular apps.
+
+   It registers `@angular-devkit/build-optimizer` as a rollup plugin, to get
    better optimization. It also uses ESM5 format inputs, as this is what
    build-optimizer is hard-coded to look for and transform.
+
+   [rollup_bundle]: https://bazelbuild.github.io/rules_nodejs/rollup/rollup_bundle.html
 """
 
 load("@build_bazel_rules_nodejs//internal/rollup:rollup_bundle.bzl",
@@ -51,6 +55,13 @@ def _use_plain_rollup(ctx):
 
 
 def run_brotli(ctx, input, output):
+  """Execute the Brotli compression utility.
+
+  Args:
+    ctx: Bazel's rule execution context
+    input: any file
+    output: the compressed file
+  """
   ctx.actions.run(
       executable = ctx.executable._brotli,
       inputs = [input],
@@ -126,10 +137,14 @@ def _ng_rollup_bundle(ctx):
 ng_rollup_bundle = rule(
     implementation = _ng_rollup_bundle,
     attrs = dict(ROLLUP_ATTRS, **{
-        "deps": attr.label_list(aspects = [
-            rollup_module_mappings_aspect,
-            esm5_outputs_aspect,
-        ]),
+        "deps": attr.label_list(
+            doc = """Other targets that provide JavaScript files.
+            Typically this will be `ts_library` or `ng_module` targets.""",
+            aspects = [
+                rollup_module_mappings_aspect,
+                esm5_outputs_aspect,
+            ]
+        ),
         "_rollup": attr.label(
             executable = True,
             cfg = "host",
@@ -143,3 +158,13 @@ ng_rollup_bundle = rule(
         "build_es5_min_compressed": "%{name}.min.js.br",
     }),
 )
+"""
+Run [Rollup] with the [Build Optimizer] plugin.
+
+This rule extends from the [rollup_bundle] rule, so attributes and outputs of
+that rule are used here too.
+
+[Rollup]: https://rollupjs.org/
+[Build Optimizer]: https://www.npmjs.com/package/@angular-devkit/build-optimizer
+[rollup_bundle]: https://bazelbuild.github.io/rules_nodejs/rollup/rollup_bundle.html
+"""

packages/bazel/src/protractor/protractor_web_test.bzl

@@ -2,8 +2,7 @@
 #
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
-"""Implementation of the protractor_web_test and protractor_web_test_suite rules.
-"""
+"Run end-to-end tests with Protractor"
 
 load("@build_bazel_rules_nodejs//internal:node.bzl",
     "sources_aspect",