PY-17657 If docstring format contains both tags and sections, tags are stronger heuristic

Otherwise any reStructuredText/Epydoc docstring that contains
text, like "Example:" or "Args:", is incorrectly interpreted as Google
Code Style docstring and then wrong format breaks parsing of parameter
declaration and type references inside.

diff --git a/python/src/com/jetbrains/python/documentation/docstrings/DocStringUtil.java b/python/src/com/jetbrains/python/documentation/docstrings/DocStringUtil.java
index ca0e57a6ac1393f9506ad63abb0e510fb1219064..7ffcd24ac7425364a79339af5f36d8a3dfb42530 100644 (file)
--- a/python/src/com/jetbrains/python/documentation/docstrings/DocStringUtil.java
+++ b/python/src/com/jetbrains/python/documentation/docstrings/DocStringUtil.java
@@ -148,18 +148,18 @@ public class DocStringUtil {
    */
   @NotNull
   public static DocStringFormat guessDocStringFormat(@NotNull String text) {
-    if (isLikeNumpyDocstring(text)) {
-      return DocStringFormat.NUMPY;
-    }
-    if (isLikeGoogleDocString(text)) {
-      return DocStringFormat.GOOGLE;
-    }
     if (isLikeEpydocDocString(text)) {
       return DocStringFormat.EPYTEXT;
     }
     if (isLikeSphinxDocString(text)) {
       return DocStringFormat.REST;
     }
+    if (isLikeNumpyDocstring(text)) {
+      return DocStringFormat.NUMPY;
+    }
+    if (isLikeGoogleDocString(text)) {
+      return DocStringFormat.GOOGLE;
+    }
     return DocStringFormat.PLAIN;
   }
 

diff --git a/python/testSrc/com/jetbrains/python/PySectionBasedDocStringTest.java b/python/testSrc/com/jetbrains/python/PySectionBasedDocStringTest.java
index 166da2926731f52ad7b878d060568884a624de0f..19b6624a45114dcfd4ba35ba634d455d37c6b0fa 100644 (file)
--- a/python/testSrc/com/jetbrains/python/PySectionBasedDocStringTest.java
+++ b/python/testSrc/com/jetbrains/python/PySectionBasedDocStringTest.java
@@ -18,10 +18,7 @@ package com.jetbrains.python;
 import com.intellij.psi.PsiElement;
 import com.intellij.psi.search.PsiElementProcessor;
 import com.intellij.psi.util.PsiTreeUtil;
-import com.jetbrains.python.documentation.docstrings.DocStringUtil;
-import com.jetbrains.python.documentation.docstrings.GoogleCodeStyleDocString;
-import com.jetbrains.python.documentation.docstrings.NumpyDocString;
-import com.jetbrains.python.documentation.docstrings.SectionBasedDocString;
+import com.jetbrains.python.documentation.docstrings.*;
 import com.jetbrains.python.documentation.docstrings.SectionBasedDocString.Section;
 import com.jetbrains.python.documentation.docstrings.SectionBasedDocString.SectionField;
 import com.jetbrains.python.fixtures.PyTestCase;
@@ -388,6 +385,23 @@ public class PySectionBasedDocStringTest extends PyTestCase {
     assertEquals("Bar", params.get(1).getType());
   }
 
+  // PY-17657, PY-16303
+  public void testNotGoogleFormatIfDocstringContainTags() {
+    assertEquals(DocStringFormat.REST, DocStringUtil.guessDocStringFormat("\"\"\"\n" +
+                                                                          ":type sub_field: FieldDescriptor | () -> FieldDescriptor\n" +
+                                                                          ":param sub_field: The type of field in this collection\n" +
+                                                                          "    Tip: You can pass a ValueObject class here to ...\n" +
+                                                                          "    Example:\n" +
+                                                                          "        addresses = field.Collection(AddressObject)\n" +
+                                                                          "\"\"\""));
+    
+    assertEquals(DocStringFormat.REST, DocStringUtil.guessDocStringFormat("\"\"\"\n" +
+                                                                          "Args:\n" +
+                                                                          "    :param Tuple[int, int] name: Some description\n" +
+                                                                          "\"\"\""));
+    
+  }
+
   @Override
   protected String getTestDataPath() {
     return super.getTestDataPath() + "/docstrings";