feat: add doc helpers (#2)

* add stardoc helpers

* fix incorrect default template in stardoc_with_diff_test()

* add stardoc helpers

* fix failing build for docs.md; add templates; cleanup

docs/BUILD.bazel

@@ -1,56 +1,34 @@
 # These loads are in the docs/ package rather than anything users depend on
 # so that the dependency on stardoc doesn't leak to them.
-load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
-load("@bazel_skylib//rules:write_file.bzl", "write_file")
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 
-# Dictionary mapping from the label of a starlark module
+stardoc_with_diff_test(
-# (like //lib:some.bzl) to the markdown file in this
+    bzl_library_target = "//lib:docs",
-# folder where the API docs are written.
+    out_label = "//docs:docs.md",
-_DOCS = {
-    "//lib:expand_make_vars.bzl": "expand_make_vars.md",
-    "//lib:params_file.bzl": "params_file.md",
-    "//lib:utils.bzl": "utils.md",
-    "//lib:paths.bzl": "paths.md",
-}
-
-[
-    stardoc(
-        name = md + "_gen",
-        out = md + "_",
-        input = tgt,
-        deps = [tgt.replace(".bzl", "")],
-    )
-    for [
-        tgt,
-        md,
-    ] in _DOCS.items()
-]
-
-[
-    diff_test(
-        name = "check_" + md,
-        failure_message = "Run bazel run //docs:update",
-        file1 = md,
-        file2 = md + "_",
-    )
-    for md in _DOCS.values()
-]
-
-write_file(
-    name = "gen_update",
-    out = "update.sh",
-    content = [
-        "#!/usr/bin/env bash",
-        "cd $BUILD_WORKSPACE_DIRECTORY",
-    ] + [
-        "cp -fv bazel-bin/docs/{0}_ docs/{0}".format(md)
-        for md in _DOCS.values()
-    ],
 )
 
-sh_binary(
+stardoc_with_diff_test(
+    bzl_library_target = "//lib:expand_make_vars",
+    out_label = "//docs:expand_make_vars.md",
+)
+
+stardoc_with_diff_test(
+    bzl_library_target = "//lib:params_file",
+    func_template = "//docs/templates:func_html.vm",
+    out_label = "//docs:params_file.md",
+)
+
+stardoc_with_diff_test(
+    bzl_library_target = "//lib:paths",
+    out_label = "//docs:paths.md",
+)
+
+stardoc_with_diff_test(
+    bzl_library_target = "//lib:utils",
+    out_label = "//docs:utils.md",
+)
+
+update_docs(
     name = "update",
-    srcs = ["update.sh"],
+    docs_folder = "docs",
-    data = [md + "_" for md in _DOCS.values()],
 )

docs/docs.md

@@ -0,0 +1,65 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Public API for docs helpers
+
+<a id="#stardoc_with_diff_test"></a>
+
+## stardoc_with_diff_test
+
+<pre>
+stardoc_with_diff_test(<a href="#stardoc_with_diff_test-bzl_library_target">bzl_library_target</a>, <a href="#stardoc_with_diff_test-out_label">out_label</a>, <a href="#stardoc_with_diff_test-aspect_template">aspect_template</a>, <a href="#stardoc_with_diff_test-func_template">func_template</a>,
+                       <a href="#stardoc_with_diff_test-header_template">header_template</a>, <a href="#stardoc_with_diff_test-provider_template">provider_template</a>, <a href="#stardoc_with_diff_test-rule_template">rule_template</a>)
+</pre>
+
+Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`.
+
+This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="stardoc_with_diff_test-bzl_library_target"></a>bzl_library_target |  the label of the <code>bzl_library</code> target to generate documentation for   |  none |
+| <a id="stardoc_with_diff_test-out_label"></a>out_label |  the label of the output MD file   |  none |
+| <a id="stardoc_with_diff_test-aspect_template"></a>aspect_template |  the label or path to the Velocity aspect template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm"</code> |
+| <a id="stardoc_with_diff_test-func_template"></a>func_template |  the label or path to the Velocity function/macro template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm"</code> |
+| <a id="stardoc_with_diff_test-header_template"></a>header_template |  the label or path to the Velocity header template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm"</code> |
+| <a id="stardoc_with_diff_test-provider_template"></a>provider_template |  the label or path to the Velocity provider template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm"</code> |
+| <a id="stardoc_with_diff_test-rule_template"></a>rule_template |  the label or path to the Velocity rule template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"</code> |
+
+
+<a id="#update_docs"></a>
+
+## update_docs
+
+<pre>
+update_docs(<a href="#update_docs-name">name</a>, <a href="#update_docs-docs_folder">docs_folder</a>)
+</pre>
+
+Creates a `sh_binary` target which copies over generated doc files to the local source tree.
+
+This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
+for generating, testing, and updating all doc files as follows:
+
+``` bash
+bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update
+```
+
+eg.
+
+``` bash
+bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="update_docs-name"></a>name |  the name of the <code>sh_binary</code> target   |  <code>"update"</code> |
+| <a id="update_docs-docs_folder"></a>docs_folder |  the name of the folder containing the doc files in the local source tree   |  <code>"docs"</code> |
+
+

docs/expand_make_vars.md

@@ -102,12 +102,12 @@ Expand make variables and substitute like genrule does.
 This function is the same as ctx.expand_make_variables with the additional
 genrule-like substitutions of:
 
-  - $@: The output file if it is a single file. Else triggers a build error.
+  - `$@`: The output file if it is a single file. Else triggers a build error.
-  - $(@D): The output directory. If there is only one file name in outs,
+  - `$(@D)`: The output directory. If there is only one file name in outs,
            this expands to the directory containing that file. If there are multiple files,
            this instead expands to the package's root directory in the bin tree,
            even if all generated files belong to the same subdirectory!
-  - $(RULEDIR): The output directory of the rule, that is, the directory
+  - `$(RULEDIR)`: The output directory of the rule, that is, the directory
     corresponding to the name of the package containing the rule under the bin tree.
 
 See https://docs.bazel.build/versions/main/be/general.html#genrule.cmd and
@@ -128,6 +128,6 @@ for more information of how these special variables are expanded.
 
 **RETURNS**
 
-s with the variables expanded
+`s` with the variables expanded
 
 

docs/params_file.md

@@ -2,6 +2,9 @@
 
 params_file public API
 
+
+
+
 <a id="#params_file"></a>
 
 ## params_file
@@ -15,16 +18,16 @@ Generates a UTF-8 encoded params file from a list of arguments.
 Handles variable substitutions for args.
 
 
-**PARAMETERS**
+### **Parameters**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="params_file-name"></a>name |  Name of the rule.   |  none |
 | <a id="params_file-out"></a>out |  Path of the output file, relative to this package.   |  none |
-| <a id="params_file-args"></a>args |  Arguments to concatenate into a params file.<br><br>Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.<br><br>1. Subject to predefined source/output path variables substitutions.<br><br>The predefined variables <code>execpath</code>, <code>execpaths</code>, <code>rootpath</code>, <code>rootpaths</code>, <code>location</code>, and <code>locations</code> take label parameters (e.g. <code>$(execpath //foo:bar)</code>) and substitute the file paths denoted by that label.<br><br>See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.<br><br>NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test args and genrule bazel substitions. This will be fixed in a future major release. See docs string of <code>expand_location_into_runfiles</code> macro in <code>internal/common/expand_into_runfiles.bzl</code> for more info.<br><br>2. Subject to predefined variables & custom variable substitutions.<br><br>Predefined "Make" variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.<br><br>Custom variables are also expanded including variables set through the Bazel CLI with --define=SOME_VAR=SOME_VALUE. See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.<br><br>Predefined genrule variables are not supported in this context.   |  <code>[]</code> |
+| <a id="params_file-args"></a>args |  Arguments to concatenate into a params file.  Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.  <ol> <li> Subject to predefined source/output path variables substitutions.  The predefined variables `execpath`, `execpaths`, `rootpath`, `rootpaths`, `location`, and `locations` take label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label.  See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.  NB: This $(location) substition returns the manifest file path which differs from the `*_binary` & `*_test` args and genrule bazel substitions. This will be fixed in a future major release. See docs string of `expand_location_into_runfiles` macro in `internal/common/expand_into_runfiles.bzl` for more info.</li>  <li>Subject to predefined variables & custom variable substitutions.  Predefined "Make" variables such as `$(COMPILATION_MODE)` and `$(TARGET_CPU)` are expanded. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.  Custom variables are also expanded including variables set through the Bazel CLI with `--define=SOME_VAR=SOME_VALUE`. See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.  Predefined genrule variables are not supported in this context.</li> </ol>   |  <code>[]</code> |
-| <a id="params_file-data"></a>data |  Data for $(location) expansions in args.   |  <code>[]</code> |
+| <a id="params_file-data"></a>data |  Data for <code>$(location)</code> expansions in args.   |  <code>[]</code> |
-| <a id="params_file-newline"></a>newline |  Line endings to use. One of ["auto", "unix", "windows"].<br><br>"auto" for platform-determined "unix" for LF "windows" for CRLF   |  <code>"auto"</code> |
+| <a id="params_file-newline"></a>newline |  Line endings to use. One of [`"auto"`, `"unix"`, `"windows"`].  <ul> <li>`"auto"` for platform-determined</li> <li>`"unix"` for LF</li> <li>`"windows"` for CRLF</li> </ul>   |  <code>"auto"</code> |
 | <a id="params_file-kwargs"></a>kwargs |  undocumented named arguments   |  none |
 
 

docs/templates/BUILD.bazel

@@ -0,0 +1,4 @@
+exports_files([
+    "func_html.vm",
+    "rule_html.vm",
+])

docs/templates/func_html.vm

@@ -0,0 +1,49 @@
+#**
+This func template is used for rendering HTML in parameter table cells
+*#
+#*
+Workaround for markdownCellFormat() not allowing HTML (specifically lists) to be rendered in attribute table cells.
+
+TODO: Once https://github.com/bazelbuild/bazel/pull/14230 is merged, remove this macro and replace with call to
+      util.markdownCellFormatWithHtml($attribute.docString, true)
+*#
+#macro( markdownCellFormatNoEscapeHtml $docString )#*
+  *##if ($docString.contains("<ul>") || $docString.contains("<ol>"))#*
+      *#${docString.trim().replaceAll("\n(\\s*\n)+", "<br><br>").replaceAll("\n", " ")}#*
+  *##else#*
+      *#${util.markdownCellFormat($docString)}#*
+  *##end#*
+*##end
+
+<a id="#${funcInfo.functionName}"></a>
+
+#[[##]]# ${funcInfo.functionName}
+
+<pre>
+${util.funcSummary($funcInfo)}
+</pre>
+
+${funcInfo.docString}
+
+#if (!$funcInfo.getParameterList().isEmpty())
+#[[###]]# **Parameters**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+#foreach ($param in $funcInfo.getParameterList())
+| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) #markdownCellFormatNoEscapeHtml( $param.docString ) #else <p align="center"> - </p> #end  | #if(!$param.getDefaultValue().isEmpty()) <code>$param.getDefaultValue()</code> #else none #end|
+#end
+#end
+#if (!$funcInfo.getReturn().docString.isEmpty())
+
+#[[###]]# **Returns**
+
+${funcInfo.getReturn().docString}
+#end
+#if (!$funcInfo.getDeprecated().docString.isEmpty())
+
+#[[###]]# **Deprecated**
+
+${funcInfo.getDeprecated().docString}
+#end

docs/templates/rule_html.vm

@@ -0,0 +1,37 @@
+#**
+This rule template is used for rendering HTML in attribute table cells
+*#
+#*
+Workaround for markdownCellFormat() not allowing HTML (specifically lists) to be rendered in attribute table cells.
+
+TODO: Once https://github.com/bazelbuild/bazel/pull/14230 is merged, remove this macro and replace with call to
+      util.markdownCellFormatWithHtml($attribute.docString, true)
+*#
+#macro( markdownCellFormatNoEscapeHtml $docString )#*
+  *##if ($docString.contains("<ul>") || $docString.contains("<ol>"))#*
+      *#${docString.trim().replaceAll("\n(\\s*\n)+", "<br><br>").replaceAll("\n", " ")}#*
+  *##else#*
+      *#${util.markdownCellFormat($docString)}#*
+  *##end#*
+*##end
+
+<a id="#${ruleName}"></a>
+
+#[[##]]# ${ruleName}
+
+<pre>
+${util.ruleSummary($ruleName, $ruleInfo)}
+</pre>
+
+${ruleInfo.docString}
+
+#[[###]]# **Attributes**
+
+#if (!$ruleInfo.getAttributeList().isEmpty())
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+#foreach ($attribute in $ruleInfo.getAttributeList())
+| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) #markdownCellFormatNoEscapeHtml( $attribute.docString ) #else - #end  | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
+#end
+#end

lib/BUILD.bazel

@@ -14,6 +14,13 @@ filegroup(
     visibility = ["//:__pkg__"],
 )
 
+bzl_library(
+    name = "docs",
+    srcs = ["docs.bzl"],
+    visibility = ["//visibility:public"],
+    deps = ["//lib/private:docs"],
+)
+
 bzl_library(
     name = "expand_make_vars",
     srcs = ["expand_make_vars.bzl"],

lib/docs.bzl

@@ -0,0 +1,10 @@
+"Public API for docs helpers"
+
+load(
+    "//lib/private:docs.bzl",
+    _stardoc_with_diff_test = "stardoc_with_diff_test",
+    _update_docs = "update_docs",
+)
+
+stardoc_with_diff_test = _stardoc_with_diff_test
+update_docs = _update_docs

lib/params_file.bzl

@@ -20,34 +20,38 @@ def params_file(
 
             Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.
 
-            1. Subject to predefined source/output path variables substitutions.
+            <ol>
+            <li> Subject to predefined source/output path variables substitutions.
 
             The predefined variables `execpath`, `execpaths`, `rootpath`, `rootpaths`, `location`, and `locations` take
             label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label.
 
             See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.
 
-            NB: This $(location) substition returns the manifest file path which differs from the *_binary & *_test
+            NB: This $(location) substition returns the manifest file path which differs from the `*_binary` & `*_test`
             args and genrule bazel substitions. This will be fixed in a future major release.
             See docs string of `expand_location_into_runfiles` macro in `internal/common/expand_into_runfiles.bzl`
-            for more info.
+            for more info.</li>
 
-            2. Subject to predefined variables & custom variable substitutions.
+            <li>Subject to predefined variables & custom variable substitutions.
 
-            Predefined "Make" variables such as $(COMPILATION_MODE) and $(TARGET_CPU) are expanded.
+            Predefined "Make" variables such as `$(COMPILATION_MODE)` and `$(TARGET_CPU)` are expanded.
             See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.
 
-            Custom variables are also expanded including variables set through the Bazel CLI with --define=SOME_VAR=SOME_VALUE.
+            Custom variables are also expanded including variables set through the Bazel CLI with `--define=SOME_VAR=SOME_VALUE`.
             See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.
 
-            Predefined genrule variables are not supported in this context.
+            Predefined genrule variables are not supported in this context.</li>
+            </ol>
 
-        data: Data for $(location) expansions in args.
+        data: Data for `$(location)` expansions in args.
-        newline: Line endings to use. One of ["auto", "unix", "windows"].
+        newline: Line endings to use. One of [`"auto"`, `"unix"`, `"windows"`].
 
-            "auto" for platform-determined
+            <ul>
-            "unix" for LF
+            <li>`"auto"` for platform-determined</li>
-            "windows" for CRLF
+            <li>`"unix"` for LF</li>
+            <li>`"windows"` for CRLF</li>
+            </ul>
         **kwargs: undocumented named arguments
     """
     _params_file(

lib/private/BUILD.bazel

@@ -23,6 +23,17 @@ bzl_library(
     deps = ["@bazel_skylib//lib:paths"],
 )
 
+bzl_library(
+    name = "docs",
+    srcs = ["docs.bzl"],
+    visibility = ["//lib:__subpackages__"],
+    deps = [
+        "@bazel_skylib//rules:diff_test",
+        "@bazel_skylib//rules:write_file",
+        "@io_bazel_stardoc//stardoc:stardoc_lib",
+    ],
+)
+
 bzl_library(
     name = "expand_make_vars",
     srcs = ["expand_make_vars.bzl"],

lib/private/docs.bzl

@@ -0,0 +1,98 @@
+"Helpers for generating stardoc documentation"
+
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+
+def stardoc_with_diff_test(
+        bzl_library_target,
+        out_label,
+        aspect_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm",
+        func_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm",
+        header_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm",
+        provider_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm",
+        rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"):
+    """Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`.
+
+    This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
+
+    Args:
+        bzl_library_target: the label of the `bzl_library` target to generate documentation for
+        out_label: the label of the output MD file
+        aspect_template: the label or path to the Velocity aspect template to use with stardoc
+        func_template: the label or path to the Velocity function/macro template to use with stardoc
+        header_template: the label or path to the Velocity header template to use with stardoc
+        provider_template: the label or path to the Velocity provider template to use with stardoc
+        rule_template: the label or path to the Velocity rule template to use with stardoc
+    """
+
+    out_file = out_label.replace("//", "").replace(":", "/")
+
+    # Generate MD from .bzl
+    stardoc(
+        name = out_file.replace("/", "_").replace(".md", "-docgen"),
+        out = out_file.replace(".md", "-docgen.md"),
+        input = bzl_library_target + ".bzl",
+        deps = [bzl_library_target],
+        aspect_template = aspect_template,
+        func_template = func_template,
+        header_template = header_template,
+        provider_template = provider_template,
+        rule_template = rule_template,
+    )
+
+    # Ensure that the generated MD has been updated in the local source tree
+    diff_test(
+        name = out_file.replace("/", "_").replace(".md", "-difftest"),
+        failure_message = "Please run \"bazel run //docs:update\"",
+        # Source file
+        file1 = out_label,
+        # Output from stardoc rule above
+        file2 = out_file.replace(".md", "-docgen.md"),
+    )
+
+def update_docs(
+        name = "update",
+        docs_folder = "docs"):
+    """Creates a `sh_binary` target which copies over generated doc files to the local source tree.
+
+    This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
+    for generating, testing, and updating all doc files as follows:
+
+    ``` bash
+    bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update
+    ```
+
+    eg.
+
+    ``` bash
+    bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
+    ```
+
+    Args:
+        name: the name of the `sh_binary` target
+        docs_folder: the name of the folder containing the doc files in the local source tree
+    """
+    content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"]
+    data = []
+    for r in native.existing_rules().values():
+        if r["kind"] == "stardoc":
+            doc_gen = r["out"]
+            if doc_gen.startswith(":"):
+                doc_gen = doc_gen[1:]
+            doc_dest = doc_gen.replace("-docgen.md", ".md")
+            data.append(doc_gen)
+            content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest))
+
+    update_script = name + ".sh"
+    write_file(
+        name = "gen_" + name,
+        out = update_script,
+        content = content,
+    )
+
+    native.sh_binary(
+        name = name,
+        srcs = [update_script],
+        data = data,
+    )

lib/private/expand_make_vars.bzl

@@ -107,12 +107,12 @@ def expand_variables(ctx, s, outs = [], output_dir = False, attribute_name = "ar
     This function is the same as ctx.expand_make_variables with the additional
     genrule-like substitutions of:
 
-      - $@: The output file if it is a single file. Else triggers a build error.
+      - `$@`: The output file if it is a single file. Else triggers a build error.
-      - $(@D): The output directory. If there is only one file name in outs,
+      - `$(@D)`: The output directory. If there is only one file name in outs,
                this expands to the directory containing that file. If there are multiple files,
                this instead expands to the package's root directory in the bin tree,
                even if all generated files belong to the same subdirectory!
-      - $(RULEDIR): The output directory of the rule, that is, the directory
+      - `$(RULEDIR)`: The output directory of the rule, that is, the directory
         corresponding to the name of the package containing the rule under the bin tree.
 
     See https://docs.bazel.build/versions/main/be/general.html#genrule.cmd and
@@ -127,7 +127,7 @@ def expand_variables(ctx, s, outs = [], output_dir = False, attribute_name = "ar
         attribute_name: name of the attribute containing the expression
 
     Returns:
-        s with the variables expanded
+        `s` with the variables expanded
     """
     rule_dir = [f for f in [
         ctx.bin_dir.path,

lib/private/utils.bzl

@@ -45,7 +45,7 @@ def _to_label(param):
         if not param.startswith("@") and not param.startswith("//"):
             # resolve the relative label from the current package
             # if 'param' is in another workspace, then this would return the label relative to that workspace, eg:
-            # Label("@my//foo:bar").relative("@other//baz:bill") == Label("@other//baz:bill")
+            # `Label("@my//foo:bar").relative("@other//baz:bill") == Label("@other//baz:bill")`
             if param.startswith(":"):
                 param = param[1:]
             if native.package_name():