PY-17023 Suggest different section titles for Google and Numpy docstrings

Also I removed "Params" title, since Napoleon doesn't support it and
can't render such sections.
Titles that contain multiple words are capitalized on ever word.
Actual set of headers is based on the following user suggestion:
https://youtrack.jetbrains.com/issue/PY-9795#comment=27-1122111.

diff --git a/python/src/com/jetbrains/python/documentation/docstrings/DocStringSectionHeaderCompletionContributor.java b/python/src/com/jetbrains/python/documentation/docstrings/DocStringSectionHeaderCompletionContributor.java
index 8f302299e77232800870c2a86da5de2cc6089668..b85952ccb1d2707adc8874f9564b2f82df69ec12 100644 (file)
--- a/python/src/com/jetbrains/python/documentation/docstrings/DocStringSectionHeaderCompletionContributor.java
+++ b/python/src/com/jetbrains/python/documentation/docstrings/DocStringSectionHeaderCompletionContributor.java
@@ -55,8 +55,10 @@ public class DocStringSectionHeaderCompletionContributor extends CompletionContr
                final TextRange linePrefixRange = new TextRange(document.getLineStartOffset(document.getLineNumber(offset)), offset);
                final String prefix = StringUtil.trimLeading(document.getText(linePrefixRange));
                result = result.withPrefixMatcher(prefix).caseInsensitive();
-               for (String tag : SectionBasedDocString.SECTION_NAMES) {
-                 result.addElement(LookupElementBuilder.create(StringUtil.capitalize(tag)));
+               final Iterable<String> names = format == DocStringFormat.GOOGLE ? GoogleCodeStyleDocString.PREFERRED_SECTION_HEADERS
+                                                                               : NumpyDocString.PREFERRED_SECTION_HEADERS; 
+               for (String tag : names) {
+                 result.addElement(LookupElementBuilder.create(tag));
                }
              }
            });

diff --git a/python/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java b/python/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java
index f2c9b50e01ddfa9d9f8bafc311916ec3c870d769..813e8c1a95cde8f3538ca91475d63f6e5e0794af 100644 (file)
--- a/python/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java
+++ b/python/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java
@@ -15,6 +15,7 @@
  */
 package com.jetbrains.python.documentation.docstrings;
 
+import com.google.common.collect.ImmutableList;
 import com.intellij.openapi.util.Pair;
 import com.intellij.util.containers.ContainerUtil;
 import com.jetbrains.python.toolbox.Substring;
@@ -33,6 +34,19 @@ public class GoogleCodeStyleDocString extends SectionBasedDocString {
   public static final Pattern SECTION_HEADER = Pattern.compile("^[ \t]*([\\w \t]+):[ \t]*$", Pattern.MULTILINE);
   private static final Pattern FIELD_NAME_AND_TYPE = Pattern.compile("^[ \t]*(.+?)[ \t]*\\([ \t]*(.*?)[ \t]*\\)?[ \t]*$", Pattern.MULTILINE);
 
+  public static final List<String> PREFERRED_SECTION_HEADERS = ImmutableList.of("Args",
+                                                                                "Keyword Args",
+                                                                                "Returns",
+                                                                                "Yields",
+                                                                                "Raises",
+                                                                                "Attributes",
+                                                                                "See Also",
+                                                                                "Methods",
+                                                                                "References",
+                                                                                "Examples",
+                                                                                "Notes",
+                                                                                "Warnings");
+
   public GoogleCodeStyleDocString(@NotNull Substring text) {
     super(text);
   }

diff --git a/python/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java b/python/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java
index 2402f1e45e5472373ee9c257037de8389db15e7e..7de68ab9d78230584de43e7f2b43abbbd28031ea 100644 (file)
--- a/python/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java
+++ b/python/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java
@@ -15,6 +15,7 @@
  */
 package com.jetbrains.python.documentation.docstrings;
 
+import com.google.common.collect.ImmutableList;
 import com.intellij.openapi.util.Pair;
 import com.jetbrains.python.toolbox.Substring;
 import org.jetbrains.annotations.NonNls;
@@ -34,7 +35,21 @@ public class NumpyDocString extends SectionBasedDocString {
   private static final Pattern NAME_SEPARATOR = Pattern.compile("[ \t]*,[ \t]*");
   public static final Pattern SECTION_HEADER = Pattern.compile("^[ \t]*[-=]{2,}[ \t]*$", Pattern.MULTILINE);
 
+  public static final List<String> PREFERRED_SECTION_HEADERS = ImmutableList.of("Parameters",
+                                                                                "Other Parameters",
+                                                                                "Returns",
+                                                                                "Yields",
+                                                                                "Raises",
+                                                                                "Attributes",
+                                                                                "See Also",
+                                                                                "Methods",
+                                                                                "References",
+                                                                                "Examples",
+                                                                                "Notes",
+                                                                                "Warnings"); 
+
   private Substring mySignature;
+
   public NumpyDocString(@NotNull Substring text) {
     super(text);
   }

diff --git a/python/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java b/python/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java
index 2a678c468b03eae7da969164cb31d3fc3960d9f2..b2d0d31cb864f17437866821df0d15a31f03923a 100644 (file)
--- a/python/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java
+++ b/python/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java
@@ -60,7 +60,6 @@ public abstract class SectionBasedDocString extends DocStringLineParser implemen
                 .put("arguments", PARAMETERS_SECTION)
                 .put("args", PARAMETERS_SECTION)
                 .put("parameters", PARAMETERS_SECTION)
-                .put("params", PARAMETERS_SECTION)
                 .put("keyword args", KEYWORD_ARGUMENTS_SECTION)
                 .put("keyword arguments", KEYWORD_ARGUMENTS_SECTION)
                 .put("other parameters", OTHER_PARAMETERS_SECTION)

diff --git a/python/testData/completion/secondSectionNameInGoogleDocstring.after.py b/python/testData/completion/secondSectionNameInGoogleDocstring.after.py
new file mode 100644 (file)
index 0000000..eab7cd0
--- /dev/null
+++ b/python/testData/completion/secondSectionNameInGoogleDocstring.after.py
@@ -0,0 +1,7 @@
+def f(x):
+    """
+    Args:
+      x:
+
+    Returns:
+    """
\ No newline at end of file

diff --git a/python/testData/completion/sectionNamesInNumpyDocstrings.py b/python/testData/completion/sectionNamesInNumpyDocstrings.py
new file mode 100644 (file)
index 0000000..26bbeee
--- /dev/null
+++ b/python/testData/completion/sectionNamesInNumpyDocstrings.py
@@ -0,0 +1,4 @@
+def f():
+    """
+    <caret>
+    """

diff --git a/python/testData/completion/twoWordsSectionNameInGoogleDocstring.after.py b/python/testData/completion/twoWordsSectionNameInGoogleDocstring.after.py
index 0e78f8a2f5f0adbe04ca8a524b4c17df03fc052c..b6e4ae68b4cdc7aa8042fdea120483f3445ebf9b 100644 (file)
--- a/python/testData/completion/twoWordsSectionNameInGoogleDocstring.after.py
+++ b/python/testData/completion/twoWordsSectionNameInGoogleDocstring.after.py
@@ -1,4 +1,4 @@
 def f():
     """
-    Keyword arguments:
+    Keyword Args:
     """
\ No newline at end of file

diff --git a/python/testData/completion/twoWordsSectionNameInGoogleDocstring.py b/python/testData/completion/twoWordsSectionNameInGoogleDocstring.py
index be00b1f8e67866fd6726b3906dbc9855a4600305..75094bc1054ead14375fa5262d89fef03e3c428e 100644 (file)
--- a/python/testData/completion/twoWordsSectionNameInGoogleDocstring.py
+++ b/python/testData/completion/twoWordsSectionNameInGoogleDocstring.py
@@ -1,4 +1,4 @@
 def f():
     """
-    Keyword argu<caret>:
+    Keyword ar<caret>:
     """
\ No newline at end of file

diff --git a/python/testData/docstrings/googleParametersSectionWithoutSummary.py b/python/testData/docstrings/googleParametersSectionWithoutSummary.py
index 52eb56e9f452ec410bf90d7426117aca4b2b8cc2..d937bf91caa240a9ff1e9c54d47e2afb9b625053 100644 (file)
--- a/python/testData/docstrings/googleParametersSectionWithoutSummary.py
+++ b/python/testData/docstrings/googleParametersSectionWithoutSummary.py
@@ -1,5 +1,5 @@
 def f(x):
     """
-    Params:
+    Parameters:
       x: foo
     """
\ No newline at end of file

diff --git a/python/testData/inspections/GoogleDocstringParametersInspection/test.py b/python/testData/inspections/GoogleDocstringParametersInspection/test.py
index 44a8610ab75c6ea36c7c852a33881aa843d71f8f..ab9f8b79ba5793621233e8de0e4eb7cb7bf46d4b 100644 (file)
--- a/python/testData/inspections/GoogleDocstringParametersInspection/test.py
+++ b/python/testData/inspections/GoogleDocstringParametersInspection/test.py
@@ -37,7 +37,7 @@ def compare(a, b, *, key=None):
 def foo(a, <weak_warning descr="Missing parameter c in docstring">c</weak_warning>):
   """
   
-  Params:
+  Parameters:
     a:
     <weak_warning descr="Unexpected parameter b in docstring">b</weak_warning>:
   """

diff --git a/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.after.py b/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.after.py
index d4424e0ef4e41e32ad94ab7505ddd3dd0522918d..ac36294d0bc6c82cd92219bc8a81143716031922 100644 (file)
--- a/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.after.py
+++ b/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.after.py
@@ -1,6 +1,6 @@
 def f(a, d):
     """
-    Params:
+    Parameters:
       a : foo
       d : quux
     """
\ No newline at end of file

diff --git a/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.before.py b/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.before.py
index 27d642ddbc01861eb88537120d6bbfa02d2c4f7c..64c9b7a139d94d4412fe9036a470e6c256e49d9f 100644 (file)
--- a/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.before.py
+++ b/python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.before.py
@@ -1,6 +1,6 @@
 def f(a, b, c, d):
     """
-    Params:
+    Parameters:
       a : foo
       b : bar
       c : baz

diff --git a/python/testSrc/com/jetbrains/python/PythonCompletionTest.java b/python/testSrc/com/jetbrains/python/PythonCompletionTest.java
index 4e00465d167aecfd90912455bc2c31e528afce18..57494571cd094a1a40463e6d887c0ca96b2d8451 100644 (file)
--- a/python/testSrc/com/jetbrains/python/PythonCompletionTest.java
+++ b/python/testSrc/com/jetbrains/python/PythonCompletionTest.java
@@ -408,10 +408,25 @@ public class PythonCompletionTest extends PyTestCase {
   // PY-16877
   public void testSectionNamesInGoogleDocstring() {
     runWithDocStringFormat(DocStringFormat.GOOGLE, new Runnable() {
+      @Override
+      public void run() {
+        final List<String> variants = doTestByFile();
+        assertNotNull(variants);
+        assertContainsElements(variants, "Args", "Keyword Args", "Returns");
+        assertDoesntContain(variants, "Parameters", "Return", "Yield");
+      }
+    });
+  }
+
+  // PY-17023
+  public void testSectionNamesInNumpyDocstrings() {
+    runWithDocStringFormat(DocStringFormat.NUMPY, new Runnable() {
+      @Override
       public void run() {
         final List<String> variants = doTestByFile();
         assertNotNull(variants);
-        assertContainsElements(variants, "Args", "Parameters", "Keyword arguments", "Returns");
+        assertContainsElements(variants, "Parameters", "Other Parameters", "Returns");
+        assertDoesntContain(variants, "Args", "Return", "Yield");
       }
     });
   }
@@ -421,9 +436,7 @@ public class PythonCompletionTest extends PyTestCase {
     runWithDocStringFormat(DocStringFormat.GOOGLE, new Runnable() {
       @Override
       public void run() {
-        final List<String> variants = doTestByFile();
-        assertNotNull(variants);
-        assertContainsElements(variants, "Return", "Returns");
+        doTest();
       }
     });
   }