starlark: dedent continued function param lines

This allows multi-line parameter documentation under Args: without extra indents.
Fixes bazelbuild/stardoc#74

Closes bazelbuild#12286.

PiperOrigin-RevId: 340294846

src/test/java/com/google/devtools/build/skydoc/testdata/function_basic_test/golden.txt

@@ -103,6 +103,47 @@ Use literally anything but this function.
 
 
 
+<a name="#param_doc_multiline"></a>
+
+## param_doc_multiline
+
+<pre>
+param_doc_multiline(<a href="#param_doc_multiline-complex">complex</a>)
+</pre>
+
+Has a complex parameter.
+
+### Parameters
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="param_doc_multiline-complex">
+      <td><code>complex</code></td>
+      <td>
+        required.
+        <p>
+          A parameter with some non-obvious behavior.
+
+ For example, it does things that require **multiple paragraphs** to explain.
+
+Note: we should preserve the nested indent in the following code:
+
+```json
+{
+    "key": "value"
+}
+```
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+
 <a name="#returns_a_thing"></a>
 
 ## returns_a_thing

src/test/java/com/google/devtools/build/skydoc/testdata/function_basic_test/input.bzl

@@ -54,3 +54,21 @@ def deprecated_do_not_use():
 
 def undocumented_function(a, b, c):
     pass
+
+def param_doc_multiline(complex):
+    """Has a complex parameter.
+
+    Args:
+        complex: A parameter with some non-obvious behavior.
+
+            For example, it does things that require **multiple paragraphs** to explain.
+
+           Note: we should preserve the nested indent in the following code:
+
+           ```json
+           {
+               "key": "value"
+           }
+           ```
+    """
+    pass

src/test/java/com/google/devtools/build/skydoc/testdata/pure_markdown_template_test/golden.txt

@@ -56,7 +56,7 @@ Small example of function using a markdown template.
 | Name  | Description | Default Value |
 | :-------------: | :-------------: | :-------------: |
 | <a name="example_function-foo"></a>foo |  This parameter does foo related things.   |  none |
-| <a name="example_function-bar"></a>bar |  This parameter does bar related things.   |  <code>"bar"</code> |
+| <a name="example_function-bar"></a>bar |  This parameter does bar related things.<br><br>For example, it does things that require **multiple paragraphs** to explain.<br><br>Note: we should preserve the nested indent in the following code:<br><br><pre><code>json {     "key": "value" } </code></pre>   |  <code>"bar"</code> |
 
 
 <a name="#example_aspect"></a>

src/test/java/com/google/devtools/build/skydoc/testdata/pure_markdown_template_test/input.bzl

@@ -6,6 +6,16 @@ def example_function(foo, bar = "bar"):
     Args:
         foo: This parameter does foo related things.
         bar: This parameter does bar related things.
+
+            For example, it does things that require **multiple paragraphs** to explain.
+
+            Note: we should preserve the nested indent in the following code:
+
+            ```json
+            {
+                "key": "value"
+            }
+            ```
     """
     pass
 

src/tools/starlark/java/com/google/devtools/starlark/common/DocstringUtils.java

@@ -479,17 +479,25 @@ private List<ParameterDoc> parseParameters() {
     /** Parses additional lines that can come after "param: foo" in an 'Args' section. */
     private void parseContinuedParamDescription(
         int baselineIndentation, StringBuilder description) {
+      // Two iterations: first buffer lines and find the minimal indent, then trim to the min
+      List<String> buffer = new ArrayList<>();
+      int continuationIndentation = Integer.MAX_VALUE;
       while (nextLine()) {
-        if (line.isEmpty()) {
-          description.append('\n');
-          continue;
-        }
-        if (getIndentation(line) <= baselineIndentation) {
-          break;
+        if (!line.isEmpty()) {
+          if (getIndentation(line) <= baselineIndentation) {
+            break;
+          }
+          continuationIndentation = Math.min(getIndentation(line), continuationIndentation);
         }
-        String trimmedLine = line.substring(baselineIndentation);
+        buffer.add(line);
+      }
+
+      for (String bufLine : buffer) {
         description.append('\n');
-        description.append(trimmedLine);
+        if (!bufLine.isEmpty()) {
+          String trimmedLine = bufLine.substring(continuationIndentation);
+          description.append(trimmedLine);
+        }
       }
     }