From a0e5d3c9b2c3fecd86229d3fc0c0c152b503981a Mon Sep 17 00:00:00 2001
From: c-parsons <cparsons@google.com>
Date: Mon, 26 Nov 2018 14:45:08 -0500
Subject: [PATCH] update stardoc.bzl to use flag semantics instead of
 positional arguments (#126)

* update stardoc.bzl to use flag semantics instead of positional arguments

* fixed typo
---
 WORKSPACE               |  4 +---
 stardoc/BUILD           |  2 +-
 stardoc/stardoc.bzl     | 22 ++++++++++++++++++---
 test/self_doc_golden.md | 42 ++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/WORKSPACE b/WORKSPACE
index ee1bc3b..8770006 100644
--- a/WORKSPACE
+++ b/WORKSPACE
@@ -15,10 +15,8 @@ git_repository(
 git_repository(
     name = "io_bazel",
     remote = "https://github.com/bazelbuild/bazel.git",
-    # Latest tagged version at time of writing is 0.19.1, which doens't
-    # include some fixes for --incompatible_new_actions_api.
     # TODO: Update to a newer tagged version when available.
-    commit = "ba6fbded11b3b40e2680c6fca27db9563c7c2193",  # 2018-11-16
+    commit = "e7ebb7e68d35ae090d91fe6b4c92c1c831421faa",  # 2018-11-26
 )
 # Required by @io_bazel.
 # Note that @protobuf is already created in skydoc_repositories().
diff --git a/stardoc/BUILD b/stardoc/BUILD
index 75720d8..fe35657 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -17,6 +17,6 @@ stardoc(
     name = "stardoc_doc",
     out = "stardoc_doc.md",
     input = ":stardoc.bzl",
-    symbol_names = ["stardoc"],
+    symbol_names = ["stardoc", "_stardoc_impl"],
     deps = [":stardoc_lib"],
 )
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index 5046469..61eef2e 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -18,15 +18,20 @@ load("@bazel_skylib//:skylark_library.bzl", "SkylarkLibraryInfo")
 
 def _stardoc_impl(ctx):
     """Implementation of the stardoc rule."""
+    for semantic_flag in ctx.attr.semantic_flags:
+      if not semantic_flag.startswith("--"):
+        fail("semantic_flags entry '%s' must start with '--'" % semantic_flag)
     out_file = ctx.outputs.out
     input_files = depset(direct = [ctx.file.input], transitive = [
         dep[SkylarkLibraryInfo].transitive_srcs
         for dep in ctx.attr.deps
     ])
     args = [
-        str(ctx.file.input.owner),
-        ctx.outputs.out.path,
-    ] + ctx.attr.symbol_names
+        "--input=" + str(ctx.file.input.owner),
+        "--output=" + ctx.outputs.out.path,
+    ] + [
+        ("--symbols=" + symbol) for symbol in ctx.attr.symbol_names
+    ] + ctx.attr.semantic_flags
     stardoc = ctx.executable.stardoc
     ctx.actions.run(
         outputs = [out_file],
@@ -63,6 +68,17 @@ This rule is an experimental replacement for the existing skylark_doc rule.
 A list of symbol names to generate documentation for. These should correspond to
 the names of rule definitions in the input file. If this list is empty, then
 documentation for all exported rule definitions will be generated.
+""",
+            default = [],
+        ),
+        "semantic_flags": attr.string_list(
+            doc = """
+A list of canonical flags to affect Starlark semantics for the Starlark interpretter
+during documentation generation. This should only be used to maintain compatibility with
+non-default semantic flags required to use the given Starlark symbols.
+<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify
+<code>--incompatible_foo_semantic=false</code>, then this attribute should contain
+"--incompatible_foo_semantic=false".
 """,
             default = [],
         ),
diff --git a/test/self_doc_golden.md b/test/self_doc_golden.md
index aa05bb5..db9a024 100755
--- a/test/self_doc_golden.md
+++ b/test/self_doc_golden.md
@@ -2,7 +2,7 @@
 ## stardoc
 
 <pre>
-stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-stardoc">stardoc</a>, <a href="#stardoc-symbol_names">symbol_names</a>)
+stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-semantic_flags">semantic_flags</a>, <a href="#stardoc-stardoc">stardoc</a>, <a href="#stardoc-symbol_names">symbol_names</a>)
 </pre>
 
 
@@ -55,6 +55,20 @@ This rule is an experimental replacement for the existing skylark_doc rule.
         </p>
       </td>
     </tr>
+    <tr id="stardoc-semantic_flags">
+      <td><code>semantic_flags</code></td>
+      <td>
+        List of strings; optional
+        <p>
+          A list of canonical flags to affect Starlark semantics for the Starlark interpretter
+during documentation generation. This should only be used to maintain compatibility with
+non-default semantic flags required to use the given Starlark symbols.
+<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify
+<code>--incompatible_foo_semantic=false</code>, then this attribute should contain
+"--incompatible_foo_semantic=false".
+        </p>
+      </td>
+    </tr>
     <tr id="stardoc-stardoc">
       <td><code>stardoc</code></td>
       <td>
@@ -79,3 +93,29 @@ documentation for all exported rule definitions will be generated.
 </table>
 
 
+## _stardoc_impl
+
+<pre>
+_stardoc_impl(<a href="#_stardoc_impl-ctx">ctx</a>)
+</pre>
+
+Implementation of the stardoc rule.
+
+### Parameters
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="_stardoc_impl-ctx>
+      <td><code>ctx</code></td>
+      <td>
+        required.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+