Skylint: docstring format: warn about wrong order of sections only once

RELNOTES: none
PiperOrigin-RevId: 173257316

2 files changed, 25 insertions, 1 deletions

diff --git a/src/tools/skylark/java/com/google/devtools/skylark/skylint/DocstringUtils.java b/src/tools/skylark/java/com/google/devtools/skylark/skylint/DocstringUtils.java
index 4d556543a6..1d37bc6389 100644
--- a/src/tools/skylark/java/com/google/devtools/skylark/skylint/DocstringUtils.java
+++ b/src/tools/skylark/java/com/google/devtools/skylark/skylint/DocstringUtils.java
@@ -328,6 +328,7 @@ public final class DocstringUtils {
       List<ParameterDoc> params = new ArrayList<>();
       String returns = "";
       String deprecated = "";
+      boolean descriptionBodyAfterSpecialSectionsReported = false;
       while (!eof()) {
         switch (line) {
           case "Args:":
@@ -352,8 +353,9 @@ public final class DocstringUtils {
             deprecated = parseSectionAfterHeading();
             break;
           default:
-            if (specialSectionsStarted) {
+            if (specialSectionsStarted && !descriptionBodyAfterSpecialSectionsReported) {
               error("description body should go before the special sections");
+              descriptionBodyAfterSpecialSectionsReported = true;
             }
             if (deprecated.isEmpty() && nonStandardDeprecation.isEmpty()) {
               nonStandardDeprecation = checkForNonStandardDeprecation(line);
diff --git a/src/tools/skylark/javatests/com/google/devtools/skylark/skylint/DocstringUtilsTest.java b/src/tools/skylark/javatests/com/google/devtools/skylark/skylint/DocstringUtilsTest.java
index 56c5e2b073..888407c63e 100644
--- a/src/tools/skylark/javatests/com/google/devtools/skylark/skylint/DocstringUtilsTest.java
+++ b/src/tools/skylark/javatests/com/google/devtools/skylark/skylint/DocstringUtilsTest.java
@@ -377,6 +377,28 @@ public class DocstringUtilsTest {
   }
 
   @Test
+  public void noRepeatedErrorAboutWrongOrder() throws Exception {
+    List<DocstringParseError> errors = new ArrayList<>();
+    DocstringInfo info =
+        DocstringUtils.parseDocstring(
+            "summary\n"
+                + "\n"
+                + "  Args:\n"
+                + "    param1: foo\n"
+                + "\n"
+                + "  line 1\n"
+                + "  line 2\n",
+            2,
+            errors);
+    Truth.assertThat(info.summary).isEqualTo("summary");
+    Truth.assertThat(info.parameters).hasSize(1);
+    Truth.assertThat(info.longDescription).isEqualTo("line 1\nline 2");
+    Truth.assertThat(errors).hasSize(1);
+    Truth.assertThat(errors.get(0).toString())
+        .isEqualTo("6: description body should go before the special sections");
+  }
+
+  @Test
   public void invalidParameterDoc() throws Exception {
     List<DocstringParseError> errors = new ArrayList<>();
     DocstringInfo info =