PY-43035: Fix multiline sections in section-based docstrings

Now when parse docstring we take into account the block type. For OPTIONAL_TYPE sections such as Returns and Yields we don't require additional indent for lines following the summary. IJ-MR-95356 (cherry picked from commit 5dd7adf5f9042204a29b731a3a7379cc3c743af9) GitOrigin-RevId: 0393ed61220358c62b4b5d5b0547be6d12e2090c

PY-43035: Fix multiline sections in section-based docstrings
Now when parse docstring we take into account the block type. For OPTIONAL_TYPE sections such as Returns and Yields we don't require additional indent for lines following the summary. IJ-MR-95356 (cherry picked from commit 5dd7adf5f9042204a29b731a3a7379cc3c743af9) GitOrigin-RevId: 0393ed61220358c62b4b5d5b0547be6d12e2090c
4dee4ad5 · Irina.Fediaeva · intellij-monorepo-bot · 3f511c44 · 4dee4ad5 · 4dee4ad5
Commit 4dee4ad5 authored 2 years ago by Irina.Fediaeva Committed by intellij-monorepo-bot 2 years ago
Hide whitespace changes
Inline Side-by-side

Showing

with 61 additions and 4 deletions
+61 -4
--- a/python/python-psi-impl/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java
+++ b/python/python-psi-impl/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java
@@ -150,11 +150,9 @@ public class GoogleCodeStyleDocString extends SectionBasedDocString {
    }

    if (description != null) {
-      // parse line with indentation at least one space greater than indentation of the field
-      final Pair<List<Substring>, Integer> pair = parseIndentedBlock(lineNum + 1, getLineIndentSize(lineNum));
+      final Pair<List<Substring>, Integer> pair = parseFieldContinuation(lineNum, fieldType);
      final List<Substring> nestedBlock = pair.getFirst();
      if (!nestedBlock.isEmpty()) {
-        //noinspection ConstantConditions
        description = description.union(ContainerUtil.getLastItem(nestedBlock));
      }
      description = description.trim();

--- a/python/python-psi-impl/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java
+++ b/python/python-psi-impl/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java
@@ -140,7 +140,7 @@ public class NumpyDocString extends SectionBasedDocString {
    if (namesPart == null && !isValidType(type.toString())) {
      return Pair.create(null, lineNum);
    }
-    final Pair<List<Substring>, Integer> parsedDescription = parseIndentedBlock(lineNum + 1, getLineIndentSize(lineNum));
+    final Pair<List<Substring>, Integer> parsedDescription = parseFieldContinuation(lineNum, kind);
    final List<Substring> descriptionLines = parsedDescription.getFirst();
    if (!descriptionLines.isEmpty()) {
      description = descriptionLines.get(0).union(descriptionLines.get(descriptionLines.size() - 1));

--- a/python/python-psi-impl/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java
+++ b/python/python-psi-impl/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java
@@ -30,6 +30,8 @@ import org.jetbrains.annotations.Nullable;
 import java.util.*;
 import java.util.regex.Pattern;

+import static com.jetbrains.python.documentation.docstrings.SectionBasedDocString.FieldType.OPTIONAL_TYPE;
+
 /**
 * Common base class for docstring styles supported by Napoleon Sphinx extension.
 *
@@ -221,6 +223,13 @@ public abstract class SectionBasedDocString extends DocStringLineParser implemen
           isSectionStart(lineNum);
  }

+  @NotNull
+  protected Pair<List<Substring>, Integer> parseFieldContinuation(int lineNum, @NotNull FieldType fieldType) {
+    int indent = getLineIndentSize(lineNum);
+    // we don't need additional indentation for Yields and Returns sections
+    return parseIndentedBlock(lineNum + 1, fieldType == OPTIONAL_TYPE ? indent - 1 : indent);
+  }
+
  /**
   * Consumes all lines that are indented more than {@code blockIndent} and don't contain start of a new section.
   * Trailing empty lines (e.g. due to indentation of closing triple quotes) are omitted in result.

--- a/python/testData/quickdoc/MultilineReturnSectionGoogle.html
+++ b/python/testData/quickdoc/MultilineReturnSectionGoogle.html
+<html><body><div class='definition'><pre><a href="psi_element://#module#MultilineReturnSectionGoogle">MultilineReturnSectionGoogle</a><br>def <b>foo</b>() -&gt; <a href="psi_element://#typename#bool">bool</a></pre></div><div class='content'>Unittest placeholder</div><table class='sections'><tr><td valign='top' class='section'><p>Returns:</td><td valign='top'>True if successful, False otherwise.
+
+The return type is optional and may be specified at the beginning of
+the Returns section followed by a colon.
+
+The Returns section may span multiple lines and paragraphs.
+Following lines should be indented to match the first line.</td></table></body></html>
\ No newline at end of file
--- a/python/testData/quickdoc/MultilineReturnSectionGoogle.py
+++ b/python/testData/quickdoc/MultilineReturnSectionGoogle.py
+def fo<the_ref>o():
+    """
+    Returns:
+        bool: True if successful, False otherwise.
+
+        The return type is optional and may be specified at the beginning of
+        the Returns section followed by a colon.
+
+        The Returns section may span multiple lines and paragraphs.
+        Following lines should be indented to match the first line.
+    """
+    pass
\ No newline at end of file
--- a/python/testData/quickdoc/MultilineReturnSectionNumpy.html
+++ b/python/testData/quickdoc/MultilineReturnSectionNumpy.html
+<html><body><div class='definition'><pre><a href="psi_element://#module#MultilineReturnSectionNumpy">MultilineReturnSectionNumpy</a><br>def <b>foo</b>() -&gt; <a href="psi_element://#typename#bool">bool</a></pre></div><div class='content'>Unittest placeholder</div><table class='sections'><tr><td valign='top' class='section'><p>Returns:</td><td valign='top'>True if successful, False otherwise.
+
+The return type is optional and may be specified at the beginning of
+the Returns section followed by a colon.
+
+The Returns section may span multiple lines and paragraphs.
+Following lines should be indented to match the first line.</td></table></body></html>
\ No newline at end of file
--- a/python/testData/quickdoc/MultilineReturnSectionNumpy.py
+++ b/python/testData/quickdoc/MultilineReturnSectionNumpy.py
+def fo<the_ref>o():
+    """
+    Returns
+    -------
+        bool
+            True if successful, False otherwise.
+
+            The return type is optional and may be specified at the beginning of
+            the Returns section followed by a colon.
+
+            The Returns section may span multiple lines and paragraphs.
+            Following lines should be indented to match the first line.
+    """
+    pass
\ No newline at end of file
--- a/python/testSrc/com/jetbrains/python/PyQuickDocTest.java
+++ b/python/testSrc/com/jetbrains/python/PyQuickDocTest.java
@@ -721,6 +721,16 @@ public class PyQuickDocTest extends LightMarkedTestCase {
    checkHTMLOnly();
  }

+  // PY-43035
+  public void testMultilineReturnSectionGoogle() {
+    checkHTMLOnly();
+  }
+
+  // PY-43035
+  public void testMultilineReturnSectionNumpy() {
+    checkHTMLOnly();
+  }
+
  @Override
  protected String getTestDataPath() {
    return super.getTestDataPath() + "/quickdoc/";