MDS/openide
1
0
Fork 0
mirror of https://gitflic.ru/project/openide/openide.git synced 2026-04-20 21:41:24 +07:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Mikhail Golubev
2015-09-25 18:58:32 +03:00
parent 56ada7d547
commit a7e6b8b064
13 changed files with 67 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
python/src/com/jetbrains/python/documentation/docstrings/DocStringSectionHeaderCompletionContributor.java
View File

@@ -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));
}
}
});

14
python/src/com/jetbrains/python/documentation/docstrings/GoogleCodeStyleDocString.java
View File

@@ -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);
}

15
python/src/com/jetbrains/python/documentation/docstrings/NumpyDocString.java
View File

@@ -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);
}

1
python/src/com/jetbrains/python/documentation/docstrings/SectionBasedDocString.java
View File

@@ -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)

7
python/testData/completion/secondSectionNameInGoogleDocstring.after.py Normal file
View File

@@ -0,0 +1,7 @@
def f(x):
"""
Args:
x:
Returns:
"""

4
python/testData/completion/sectionNamesInNumpyDocstrings.py Normal file
View File

@@ -0,0 +1,4 @@
def f():
"""
<caret>
"""

2
python/testData/completion/twoWordsSectionNameInGoogleDocstring.after.py
View File

@@ -1,4 +1,4 @@
def f():
"""
Keyword arguments:
Keyword Args:
"""

2
python/testData/completion/twoWordsSectionNameInGoogleDocstring.py
View File

@@ -1,4 +1,4 @@
def f():
"""
Keyword argu<caret>:
Keyword ar<caret>:
"""

2
python/testData/docstrings/googleParametersSectionWithoutSummary.py
View File

@@ -1,5 +1,5 @@
def f(x):
"""
Params:
Parameters:
x: foo
"""

2
python/testData/inspections/GoogleDocstringParametersInspection/test.py
View File

@@ -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>:
"""

2
python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.after.py
View File

@@ -1,6 +1,6 @@
def f(a, d):
"""
Params:
Parameters:
a : foo
d : quux
"""

2
python/testData/refactoring/changeSignature/fixGoogleDocStringRemoveMultiple.before.py
View File

@@ -1,6 +1,6 @@
def f(a, b, c, d):
"""
Params:
Parameters:
a : foo
b : bar
c : baz

21
python/testSrc/com/jetbrains/python/PythonCompletionTest.java
View File

@@ -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", "Parameters", "Keyword arguments", "Returns");
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, "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();
}
});
}