Examples with StructuredDocString com.jetbrains.python.psi.StructuredDocString used on opensource projects

Example 1 with StructuredDocString

use of com.jetbrains.python.psi.StructuredDocString in project intellij-community by JetBrains.

the class PyStructuredDocstringFormatter method formatParameterDescriptions.

private static void formatParameterDescriptions(@NotNull final StructuredDocString docString, @NotNull final StringBuilder result, boolean keyword) {
    final List<String> parameters = keyword ? docString.getKeywordArguments() : docString.getParameters();
    if (parameters.size() > 0) {
        result.append("<br><b>").append(keyword ? "Keyword arguments:" : "Parameters").append("</b><br>");
        for (String parameter : parameters) {
            final String description = keyword ? docString.getKeywordArgumentDescription(parameter) : docString.getParamDescription(parameter);
            result.append("<b>");
            result.append(parameter);
            result.append("</b>: ");
            if (description != null) {
                result.append(description);
            }
            final String paramType = docString.getParamType(parameter);
            if (paramType != null) {
                result.append(" <i>Type: ").append(paramType).append("</i>");
            }
            result.append("<br>");
        }
    }
}

Example 2 with StructuredDocString

use of com.jetbrains.python.psi.StructuredDocString in project intellij-community by JetBrains.

the class DocStringReferenceProvider method getReferencesByElement.

@NotNull
@Override
public PsiReference[] getReferencesByElement(@NotNull final PsiElement element, @NotNull ProcessingContext context) {
    if (element == DocStringUtil.getParentDefinitionDocString(element)) {
        final PyStringLiteralExpression expr = (PyStringLiteralExpression) element;
        final List<TextRange> ranges = expr.getStringValueTextRanges();
        final String exprText = expr.getText();
        final TextRange textRange = PyStringLiteralExpressionImpl.getNodeTextRange(exprText);
        final String text = textRange.substring(exprText);
        if (!ranges.isEmpty()) {
            final List<PsiReference> result = new ArrayList<>();
            final int offset = ranges.get(0).getStartOffset();
            // XXX: It does not work with multielement docstrings
            StructuredDocString docString = DocStringUtil.parse(text, element);
            if (docString instanceof TagBasedDocString) {
                final TagBasedDocString taggedDocString = (TagBasedDocString) docString;
                result.addAll(referencesFromNames(expr, offset, docString, taggedDocString.getTagArguments(TagBasedDocString.PARAM_TAGS), ReferenceType.PARAMETER));
                result.addAll(referencesFromNames(expr, offset, docString, taggedDocString.getTagArguments(TagBasedDocString.PARAM_TYPE_TAGS), ReferenceType.PARAMETER_TYPE));
                result.addAll(referencesFromNames(expr, offset, docString, docString.getKeywordArgumentSubstrings(), ReferenceType.KEYWORD));
                result.addAll(referencesFromNames(expr, offset, docString, taggedDocString.getTagArguments("var"), ReferenceType.VARIABLE));
                result.addAll(referencesFromNames(expr, offset, docString, taggedDocString.getTagArguments("cvar"), ReferenceType.CLASS_VARIABLE));
                result.addAll(referencesFromNames(expr, offset, docString, taggedDocString.getTagArguments("ivar"), ReferenceType.INSTANCE_VARIABLE));
                result.addAll(returnTypes(element, docString, offset));
            } else if (docString instanceof SectionBasedDocString) {
                final SectionBasedDocString sectioned = (SectionBasedDocString) docString;
                result.addAll(referencesFromFields(expr, offset, sectioned.getParameterFields(), ReferenceType.PARAMETER));
                result.addAll(referencesFromFields(expr, offset, sectioned.getKeywordArgumentFields(), ReferenceType.KEYWORD));
                result.addAll(referencesFromFields(expr, offset, sectioned.getAttributeFields(), PyUtil.isTopLevel(element) ? ReferenceType.GLOBAL_VARIABLE : ReferenceType.INSTANCE_VARIABLE));
                result.addAll(referencesFromFields(expr, offset, sectioned.getReturnFields(), null));
            }
            return result.toArray(new PsiReference[result.size()]);
        }
    }
    return PsiReference.EMPTY_ARRAY;
}

Example 3 with StructuredDocString

use of com.jetbrains.python.psi.StructuredDocString in project intellij-community by JetBrains.

the class DocStringReferenceProvider method referencesFromNames.

private static List<PsiReference> referencesFromNames(@NotNull PyStringLiteralExpression element, int offset, @NotNull StructuredDocString docString, @NotNull List<Substring> paramNames, @NotNull ReferenceType refType) {
    List<PsiReference> result = new ArrayList<>();
    for (Substring name : paramNames) {
        final String s = name.toString();
        if (PyNames.isIdentifier(s)) {
            final TextRange range = name.getTextRange().shiftRight(offset);
            result.add(new DocStringParameterReference(element, range, refType));
        }
        if (refType.equals(ReferenceType.PARAMETER_TYPE)) {
            final Substring type = docString.getParamTypeSubstring(s);
            if (type != null) {
                result.addAll(parseTypeReferences(element, type, offset));
            }
        }
    }
    return result;
}

Example 4 with StructuredDocString

use of com.jetbrains.python.psi.StructuredDocString in project intellij-community by JetBrains.

the class PyStructuredDocstringFormatter method formatDocstring.

/**
   * @param docstring docstring text without string literal prefix, without quotes and already escaped. 
   *                  Supposedly result of {@link PyStringLiteralExpression#getStringValue()}.
   */
@Nullable
public static List<String> formatDocstring(@NotNull final PsiElement element, @NotNull final String docstring) {
    Module module = ModuleUtilCore.findModuleForPsiElement(element);
    if (module == null) {
        final Module[] modules = ModuleManager.getInstance(element.getProject()).getModules();
        if (modules.length == 0)
            return Lists.newArrayList();
        module = modules[0];
    }
    if (module == null)
        return Lists.newArrayList();
    final List<String> result = new ArrayList<>();
    final String preparedDocstring = PyIndentUtil.removeCommonIndent(docstring, true).trim();
    final DocStringFormat format = DocStringUtil.guessDocStringFormat(preparedDocstring, element);
    if (format == DocStringFormat.PLAIN) {
        return null;
    }
    final StructuredDocString structuredDocString = DocStringUtil.parseDocStringContent(format, preparedDocstring);
    final String output = runExternalTool(module, format, preparedDocstring);
    if (output != null) {
        result.add(output);
    } else {
        result.add(structuredDocString.getDescription());
    }
    // Information about parameters in Epytext-style docstrings are formatter on our side
    if (format == DocStringFormat.EPYTEXT) {
        result.add(formatStructuredDocString(structuredDocString));
    }
    return result;
}

Example 5 with StructuredDocString

use of com.jetbrains.python.psi.StructuredDocString in project intellij-community by JetBrains.

the class PyStructuredDocstringFormatter method formatStructuredDocString.

private static String formatStructuredDocString(@NotNull final StructuredDocString docString) {
    final StringBuilder result = new StringBuilder();
    final String attributeDescription = docString.getAttributeDescription();
    if (attributeDescription != null) {
        result.append(attributeDescription);
        final String attrType = docString.getParamType(null);
        if (attrType != null) {
            result.append(" <i>Type: ").append(attrType).append("</i>");
        }
    }
    formatParameterDescriptions(docString, result, false);
    formatParameterDescriptions(docString, result, true);
    final String returnDescription = docString.getReturnDescription();
    final String returnType = docString.getReturnType();
    if (returnDescription != null || returnType != null) {
        result.append("<br><b>Return value:</b><br>");
        if (returnDescription != null) {
            result.append(returnDescription);
        }
        if (returnType != null) {
            result.append(" <i>Type: ").append(returnType).append("</i>");
        }
    }
    final List<String> raisedException = docString.getRaisedExceptions();
    if (raisedException.size() > 0) {
        result.append("<br><b>Raises:</b><br>");
        for (String s : raisedException) {
            result.append("<b>").append(s).append("</b> - ").append(docString.getRaisedExceptionDescription(s)).append("<br>");
        }
    }
    if (docString instanceof TagBasedDocString) {
        final TagBasedDocString taggedDocString = (TagBasedDocString) docString;
        final List<String> additionalTags = taggedDocString.getAdditionalTags();
        if (!additionalTags.isEmpty()) {
            result.append("<br/><br/><b>Additional:</b><br/>");
            result.append("<table>");
            for (String tagName : additionalTags) {
                final List<Substring> args = taggedDocString.getTagArguments(tagName);
                for (Substring arg : args) {
                    final String s = arg.toString();
                    result.append("<tr><td align=\"right\"><b>").append(tagName);
                    result.append(" ").append(s).append(":</b>");
                    result.append("</td><td>").append(taggedDocString.getTagValue(tagName, s)).append("</td></tr>");
                }
                result.append("</table>");
            }
        }
    }
    return result.toString();
}