From a096a9e2d291502b83633d10cbe4fda2f414abb1 Mon Sep 17 00:00:00 2001 From: Greg Magolan Date: Tue, 17 Dec 2019 06:24:51 -0800 Subject: [PATCH] Docs cleanup (#1457) * refactor: cleanup doc strings * docs: update docs --- docs/Built-ins.md | 46 +++++++++++++++++++ docs/TypeScript.md | 2 +- internal/npm_install/npm_umd_bundle.bzl | 11 +---- internal/providers/node_runtime_deps_info.bzl | 2 +- packages/jasmine/src/index.bzl | 2 +- packages/jasmine/src/index.from_src.bzl | 2 +- packages/karma/src/index.bzl | 2 +- packages/karma/src/index.from_src.bzl | 2 +- packages/labs/src/index.bzl | 2 +- packages/protractor/src/index.bzl | 2 +- packages/protractor/src/index.from_src.bzl | 2 +- packages/rollup/src/index.from_src.bzl | 2 +- packages/terser/src/index.from_src.bzl | 2 +- packages/typescript/src/index.bzl | 2 +- packages/typescript/src/index.from_src.bzl | 2 +- toolchains/node/BUILD.tpl | 4 +- toolchains/node/node_toolchain.bzl | 11 ++--- toolchains/node/node_toolchain_configure.bzl | 8 ++-- 18 files changed, 70 insertions(+), 36 deletions(-) diff --git a/docs/Built-ins.md b/docs/Built-ins.md index ced33266cb..7df7bdd5e1 100755 --- a/docs/Built-ins.md +++ b/docs/Built-ins.md @@ -1100,6 +1100,52 @@ Defaults to `""` +## copy_to_bin + +Copies a source file to bazel-bin at the same workspace-relative path path. + +e.g. `/foo/bar/a.txt -> /foo/bar/a.txt` + +This is useful to populate the output folder with all files needed at runtime, even +those which aren't outputs of a Bazel rule. + +This way you can run a binary in the output folder (execroot or runfiles_root) +without that program needing to rely on a runfiles helper library or be aware that +files are divided between the source tree and the output tree. + + + +### Usage + +``` +copy_to_bin(name, srcs, kwargs) +``` + + + +#### `name` + +Name of the rule. + + + + +#### `srcs` + +A List of Labels. File(s) to to copy. + + + + +#### `kwargs` + +further keyword arguments, e.g. `visibility` + + + + + + ## npm_package_bin Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel. diff --git a/docs/TypeScript.md b/docs/TypeScript.md index db44063919..378af673a4 100755 --- a/docs/TypeScript.md +++ b/docs/TypeScript.md @@ -480,7 +480,7 @@ Defaults to `//devserver:devserver` (*[label]*): Go based devserver executable for the host platform. Defaults to precompiled go binary in @npm_bazel_typescript setup by @bazel/typescript npm package -Defaults to `//devserver:devserver_linux_amd64` +Defaults to `//devserver:devserver_darwin_amd64` #### `entry_module` (*String*): The `entry_module` should be the AMD module name of the entry module such as `"__main__/src/index".` diff --git a/internal/npm_install/npm_umd_bundle.bzl b/internal/npm_install/npm_umd_bundle.bzl index 93ed23e5f5..64785fc7b3 100644 --- a/internal/npm_install/npm_umd_bundle.bzl +++ b/internal/npm_install/npm_umd_bundle.bzl @@ -104,14 +104,5 @@ npm_umd_bundle = rule( implementation = _npm_umd_bundle, attrs = NPM_UMD_ATTRS, outputs = {"umd": "%{package_name}.umd.js"}, + doc = """Node package umd bundling""", ) -"""Node package umd bundling -""" -# TODO(gregolan): add the above docstring to `doc` attribute -# once we upgrade to stardoc. Skydoc crashes with -# ``` -# File "internal/npm_package/npm_package.bzl", line 221, in -# outputs = NPM_PACKAGE_OUTPUTS, -# TypeError: rule() got an unexpected keyword argument 'doc' -# ``` -# when it encounters a `doc` attribute in a rule. diff --git a/internal/providers/node_runtime_deps_info.bzl b/internal/providers/node_runtime_deps_info.bzl index 90a6942c22..c8d358bfc1 100644 --- a/internal/providers/node_runtime_deps_info.bzl +++ b/internal/providers/node_runtime_deps_info.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Custom provider that mimics the Runfiles, but doesn't incur the expense of creating the runfiles symlink tree""" +"""Custom provider that mimics the Runfiles, but doesn't incur the expense of creating the runfiles symlink tree""" load("//internal/linker:link_node_modules.bzl", "add_arg", "write_node_modules_manifest") diff --git a/packages/jasmine/src/index.bzl b/packages/jasmine/src/index.bzl index e497e44c56..fd250a7a97 100644 --- a/packages/jasmine/src/index.bzl +++ b/packages/jasmine/src/index.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Public API surface is re-exported here. +"""Public API surface is re-exported here. """ load("//:jasmine_node_test.bzl", _jasmine_node_test = "jasmine_node_test") diff --git a/packages/jasmine/src/index.from_src.bzl b/packages/jasmine/src/index.from_src.bzl index 7aa34a0ef2..75dd546e0b 100644 --- a/packages/jasmine/src/index.from_src.bzl +++ b/packages/jasmine/src/index.from_src.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Defaults for usage without @npm//@bazel/jasmine +"""Defaults for usage without @npm//@bazel/jasmine """ load(":index.bzl", _jasmine_node_test = "jasmine_node_test") diff --git a/packages/karma/src/index.bzl b/packages/karma/src/index.bzl index 49bfa7fd36..ff67a0246e 100644 --- a/packages/karma/src/index.bzl +++ b/packages/karma/src/index.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Public API surface is re-exported here. +"""Public API surface is re-exported here. """ load( diff --git a/packages/karma/src/index.from_src.bzl b/packages/karma/src/index.from_src.bzl index f54886a687..532d1bf650 100644 --- a/packages/karma/src/index.from_src.bzl +++ b/packages/karma/src/index.from_src.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Defaults for usage without @npm//@bazel/karma +"""Defaults for usage without @npm//@bazel/karma """ load( diff --git a/packages/labs/src/index.bzl b/packages/labs/src/index.bzl index 31eae563ea..e6150688e7 100644 --- a/packages/labs/src/index.bzl +++ b/packages/labs/src/index.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Public API surface is re-exported here. +"""Public API surface is re-exported here. """ load("//protobufjs:ts_proto_library.bzl", _ts_proto_library = "ts_proto_library") diff --git a/packages/protractor/src/index.bzl b/packages/protractor/src/index.bzl index dbc6a95c38..567cdbc49d 100644 --- a/packages/protractor/src/index.bzl +++ b/packages/protractor/src/index.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Public API surface is re-exported here. +"""Public API surface is re-exported here. """ load( diff --git a/packages/protractor/src/index.from_src.bzl b/packages/protractor/src/index.from_src.bzl index 6f69f23b41..0dbb302de0 100644 --- a/packages/protractor/src/index.from_src.bzl +++ b/packages/protractor/src/index.from_src.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Defaults for usage without @npm//@bazel/protractor +"""Defaults for usage without @npm//@bazel/protractor """ load( diff --git a/packages/rollup/src/index.from_src.bzl b/packages/rollup/src/index.from_src.bzl index 74c9e5fcf0..50e472176e 100644 --- a/packages/rollup/src/index.from_src.bzl +++ b/packages/rollup/src/index.from_src.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Defaults for usage without @npm//@bazel/rollup +"""Defaults for usage without @npm//@bazel/rollup """ load(":index.bzl", _rollup_bundle = "rollup_bundle") diff --git a/packages/terser/src/index.from_src.bzl b/packages/terser/src/index.from_src.bzl index 3cc4c7b594..9231be88e5 100644 --- a/packages/terser/src/index.from_src.bzl +++ b/packages/terser/src/index.from_src.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Defaults for usage without @npm//@bazel/terser +"""Defaults for usage without @npm//@bazel/terser """ load( diff --git a/packages/typescript/src/index.bzl b/packages/typescript/src/index.bzl index a355a5b33b..d1b620ee73 100644 --- a/packages/typescript/src/index.bzl +++ b/packages/typescript/src/index.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Public API surface is re-exported here. +"""Public API surface is re-exported here. Users should not load files under "/internal" """ diff --git a/packages/typescript/src/index.from_src.bzl b/packages/typescript/src/index.from_src.bzl index 4c9214f91b..50fa461768 100644 --- a/packages/typescript/src/index.from_src.bzl +++ b/packages/typescript/src/index.from_src.bzl @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -""" Defaults for usage without @npm//@bazel/typescript +"""Defaults for usage without @npm//@bazel/typescript """ load("@build_bazel_rules_nodejs//internal/golden_file_test:golden_file_test.bzl", "golden_file_test") diff --git a/toolchains/node/BUILD.tpl b/toolchains/node/BUILD.tpl index 4c3fb3c47d..909fd9ece2 100644 --- a/toolchains/node/BUILD.tpl +++ b/toolchains/node/BUILD.tpl @@ -11,8 +11,8 @@ # 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. -""" -This BUILD file is auto-generated from toolchains/node/BUILD.tpl + +"""This BUILD file is auto-generated from toolchains/node/BUILD.tpl """ package(default_visibility = ["//visibility:public"]) diff --git a/toolchains/node/node_toolchain.bzl b/toolchains/node/node_toolchain.bzl index 3769f5a296..75657bf495 100644 --- a/toolchains/node/node_toolchain.bzl +++ b/toolchains/node/node_toolchain.bzl @@ -11,8 +11,8 @@ # 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. -""" -This module implements the node toolchain rule. + +"""This module implements the node toolchain rule. """ NodeInfo = provider( @@ -72,9 +72,8 @@ node_toolchain = rule( mandatory = False, ), }, -) -""" -Defines a node toolchain. + doc = """Defines a node toolchain. For usage see https://docs.bazel.build/versions/master/toolchains.html#defining-toolchains. -""" +""", +) diff --git a/toolchains/node/node_toolchain_configure.bzl b/toolchains/node/node_toolchain_configure.bzl index 45383c2d68..870f17f803 100644 --- a/toolchains/node/node_toolchain_configure.bzl +++ b/toolchains/node/node_toolchain_configure.bzl @@ -11,8 +11,8 @@ # 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. -""" -Defines a repository rule for configuring the node executable. + +"""Defines a repository rule for configuring the node executable. """ def _impl(repository_ctx): @@ -50,7 +50,5 @@ node_toolchain_configure = repository_rule( mandatory = False, ), }, + doc = """Creates an external repository with a node_toolchain //:toolchain target properly configured.""", ) -""" -Creates an external repository with a node_toolchain //:toolchain target properly configured. -"""