MDS/openide
1
0
Fork 0
mirror of https://gitflic.ru/project/openide/openide.git synced 2026-09-27 10:03:11 +07:00
Code Issues Packages Projects Releases Wiki Activity

PY-30359 PY-11425 Properly handle directive aliases in tag-based docstrings

Browse Source 
Namely, collect documented parameters, keyword arguments, raised
exceptions and their respective descriptions across all possible
directive aliases.
This commit is contained in:
Mikhail Golubev
2018-06-09 15:59:40 +03:00
parent f2027afd7f
commit 34d1e91b17
4 changed files with 95 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/src/com/jetbrains/python/documentation/docstrings/SphinxDocString.java
+1 -1
View File
@@ -74,7 +74,7 @@ public class SphinxDocString extends TagBasedDocString {
@Nullable
@Override
public String getParamDescription(@Nullable String paramName) {
return paramName != null ? concatTrimmedLines(getTagValue("param", paramName)) : null;
return paramName != null ? concatTrimmedLines(getTagValue(PARAM_TAGS, paramName)) : null;
}
@Override
python/src/com/jetbrains/python/documentation/docstrings/TagBasedDocString.java
+7 -6
View File
@@ -24,7 +24,6 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
@@ -187,22 +186,24 @@ public abstract class TagBasedDocString extends DocStringLineParser implements S
@Nullable
public Substring getTagValue(String[] tagNames, @NotNull String argName) {
for (String tagName : tagNames) {
Map<Substring, Substring> argValues = myArgTagValues.get(tagName);
if (argValues != null) {
return argValues.get(new Substring(argName));
final Map<Substring, Substring> argValues = myArgTagValues.get(tagName);
final Substring key = new Substring(argName);
if (argValues != null && argValues.containsKey(key)) {
return argValues.get(key);
}
}
return null;
}
public List<Substring> getTagArguments(String... tagNames) {
final List<Substring> result = new ArrayList<>();
for (String tagName : tagNames) {
final Map<Substring, Substring> map = myArgTagValues.get(tagName);
if (map != null) {
return new ArrayList<>(map.keySet());
result.addAll(map.keySet());
}
}
return Collections.emptyList();
return result;
}
@NotNull
python/testSrc/com/jetbrains/python/EpydocStringTest.java
+42
View File
@@ -23,6 +23,7 @@ import org.jetbrains.annotations.NotNull;
import java.util.List;
import static com.intellij.testFramework.UsefulTestCase.assertOrderedEquals;
import static com.intellij.testFramework.UsefulTestCase.assertSameElements;
/**
* @author yole
@@ -122,4 +123,45 @@ public class EpydocStringTest extends TestCase {
assertEquals("(ParsedDocstring, list of Field)",
EpydocString.removeInlineMarkup("C{(L{ParsedDocstring}, list of L{Field})}"));
}
public void testDifferentExceptionTags() {
final EpydocString docstring = createEpydocDocString("@raises Exception1: foo\n" +
"@except Exception2: bar");
assertSameElements(docstring.getRaisedExceptions(), "Exception1", "Exception2");
assertEquals("foo", docstring.getRaisedExceptionDescription("Exception1"));
assertEquals("bar", docstring.getRaisedExceptionDescription("Exception2"));
}
public void testFieldAliases() {
final EpydocString docstring = createEpydocDocString("@param p1: p1 description\n" +
"@parameter p2: p2 description\n" +
"@arg p3: p3 description\n" +
"@argument p4: p4 description\n" +
"\n" +
"@kwarg key1: key1 description\n" +
"@keyword key2: key2 description\n" +
"@kwparam key3: key3 description\n" +
"\n" +
"@raises Exc1: Exc1 description \n" +
"@raise Exc2: Exc2 description \n" +
"@except Exc3: Exc3 description \n" +
"@exception Exc4: Exc4 description ");
assertSameElements(docstring.getParameters(), "p1", "p2", "p3", "p4");
assertEquals("p1 description", docstring.getParamDescription("p1"));
assertEquals("p2 description", docstring.getParamDescription("p2"));
assertEquals("p3 description", docstring.getParamDescription("p3"));
assertEquals("p4 description", docstring.getParamDescription("p4"));
assertSameElements(docstring.getKeywordArguments(), "key1", "key2", "key3");
assertEquals("key1 description", docstring.getKeywordArgumentDescription("key1"));
assertEquals("key2 description", docstring.getKeywordArgumentDescription("key2"));
assertEquals("key3 description", docstring.getKeywordArgumentDescription("key3"));
assertSameElements(docstring.getRaisedExceptions(), "Exc1", "Exc2", "Exc3", "Exc4");
assertEquals("Exc1 description", docstring.getRaisedExceptionDescription("Exc1"));
assertEquals("Exc2 description", docstring.getRaisedExceptionDescription("Exc2"));
assertEquals("Exc3 description", docstring.getRaisedExceptionDescription("Exc3"));
assertEquals("Exc4 description", docstring.getRaisedExceptionDescription("Exc4"));
}
}
python/testSrc/com/jetbrains/python/SphinxDocstringTest.java
+45
View File
@@ -0,0 +1,45 @@
// Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
package com.jetbrains.python;
import com.jetbrains.python.documentation.docstrings.SphinxDocString;
import com.jetbrains.python.fixtures.PyTestCase;
import com.jetbrains.python.toolbox.Substring;
import org.intellij.lang.annotations.Language;
import org.jetbrains.annotations.NotNull;
public class SphinxDocstringTest extends PyTestCase {
private static SphinxDocString createSphinxDocstring(@Language("TEXT") @NotNull String unescapedContentWithoutQuotes) {
return new SphinxDocString(new Substring(unescapedContentWithoutQuotes));
}
public void testFieldAliases() {
final SphinxDocString docstring = createSphinxDocstring(":param p1: p1 description\n" +
":parameter p2: p2 description\n" +
":arg p3: p3 description\n" +
":argument p4: p4 description\n" +
"\n" +
":key key1: key1 description\n" +
":keyword key2: key2 description\n" +
"\n" +
":raises Exc1: Exc1 description \n" +
":raise Exc2: Exc2 description \n" +
":except Exc3: Exc3 description \n" +
":exception Exc4: Exc4 description ");
assertSameElements(docstring.getParameters(), "p1", "p2", "p3", "p4");
assertEquals("p1 description", docstring.getParamDescription("p1"));
assertEquals("p2 description", docstring.getParamDescription("p2"));
assertEquals("p3 description", docstring.getParamDescription("p3"));
assertEquals("p4 description", docstring.getParamDescription("p4"));
assertSameElements(docstring.getKeywordArguments(), "key1", "key2");
assertEquals("key1 description", docstring.getKeywordArgumentDescription("key1"));
assertEquals("key2 description", docstring.getKeywordArgumentDescription("key2"));
assertSameElements(docstring.getRaisedExceptions(), "Exc1", "Exc2", "Exc3", "Exc4");
assertEquals("Exc1 description", docstring.getRaisedExceptionDescription("Exc1"));
assertEquals("Exc2 description", docstring.getRaisedExceptionDescription("Exc2"));
assertEquals("Exc3 description", docstring.getRaisedExceptionDescription("Exc3"));
assertEquals("Exc4 description", docstring.getRaisedExceptionDescription("Exc4"));
}
}