Deprecate the ${link page.heading} syntax for referencing BE static pages.

--
MOS_MIGRATED_REVID=130374987

2 files changed, 12 insertions, 21 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java b/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
index e7d8b38251..d73bf5305e 100644
--- a/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
+++ b/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
@@ -107,17 +107,16 @@ class RuleLinkExpander {
       }
 
       // The name is not the name of a rule but is the name of a static page, such as
-      // common-definitions. Generate a link to that page, and append the page heading if
-      // specified. For example, ${link common-definitions.label-expansion} expands to
-      // common-definitions.html#label-expansion.
-      // TODO(dzc): Deprecate this in favor of the ${link static-page#heading} syntax below.
+      // common-definitions. Generate a link to that page.
       if (STATIC_PAGES.contains(name)) {
         String link = name + ".html";
-        // The fourth capture group matches the attribute name, or page heading, e.g.
-        // "label-expansion" in "common-definitions.label-expansion".
+        // For referencing headings on a static page, use the following syntax:
+        // ${link static_page_name#heading_name}, example: ${link make-variables#gendir}
         String pageHeading = matcher.group(4);
         if (pageHeading != null) {
-          link = link + "#" + pageHeading;
+          throw new IllegalArgumentException(
+              "Invalid link syntax for BE page: " + matcher.group()
+              + "\nUse ${link static-page#heading} syntax instead.");
         }
         matcher.appendReplacement(sb, Matcher.quoteReplacement(link));
         continue;
diff --git a/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java b/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
index 0e686e268d..ed08c34b0a 100644
--- a/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
+++ b/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
@@ -79,26 +79,18 @@ public class RuleLinkExpanderTest {
     assertEquals(expected, expander.expand(docs));
   }
 
-  @Test public void testStaticPageWithHeadingRef() {
-    String docs = "<a href=\"${link common-definitions.label-expansion}\">Label Expansion</a>";
-    String expected = "<a href=\"common-definitions.html#label-expansion\">Label Expansion</a>";
-    assertEquals(expected, expander.expand(docs));
-  }
-
-  @Test public void testStaticPageWithPeriodsInHeading() {
-    String docs =
-        "<a href=\"${link make-variables.predefined_variables.genrule.cmd}\">genrule cmd</a>";
-    String expected =
-        "<a href=\"make-variables.html#predefined_variables.genrule.cmd\">genrule cmd</a>";
-    assertEquals(expected, expander.expand(docs));
-  }
-
   @Test(expected = IllegalArgumentException.class)
   public void testRefNotFound() {
     String docs = "<a href=\"${link foo.bar}\">bar</a>";
     expander.expand(docs);
   }
 
+  @Test(expected = IllegalArgumentException.class)
+  public void testIncorrectStaticPageHeadingLink() {
+    String docs = "<a href=\"${link common-definitions.label-expansion}\">Label Expansion</a>";
+    expander.expand(docs);
+  }
+
   @Test public void testRuleHeadingLink() {
     String docs = "<a href=\"${link cc_library#alwayslink_lib_example}\">examples</a>";
     String expected = "<a href=\"c-cpp.html#alwayslink_lib_example\">examples</a>";