Docs cleanup (#1457)

* refactor: cleanup doc strings * docs: update docs
bazel-contrib · Dec 17, 2019 · a096a9e · a096a9e
1 parent 3818440
commit a096a9e
Show file tree

Hide file tree

Showing 18 changed files with 70 additions and 36 deletions.
diff --git 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. `<workspace_root>/foo/bar/a.txt -> <bazel-bin>/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
@@ -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
@@ -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 <module>
-#     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
-"""