python/src/com/jetbrains/python/inspections/PyIncorrectDocstringInspection.java

   1 /*
   2  * Copyright 2000-2014 JetBrains s.r.o.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 package com.jetbrains.python.inspections;
  17
  18 import com.google.common.collect.Lists;
  19 import com.google.common.collect.Maps;
  20 import com.intellij.codeInspection.LocalInspectionToolSession;
  21 import com.intellij.codeInspection.ProblemsHolder;
  22 import com.jetbrains.python.PyBundle;
  23 import com.jetbrains.python.documentation.docstrings.DocStringUtil;
  24 import com.jetbrains.python.documentation.docstrings.PlainDocString;
  25 import com.jetbrains.python.inspections.quickfix.DocstringQuickFix;
  26 import com.jetbrains.python.psi.*;
  27 import com.jetbrains.python.toolbox.Substring;
  28 import org.jetbrains.annotations.NotNull;
  29
  30 import java.util.ArrayList;
  31 import java.util.List;
  32 import java.util.Map;
  33
  34 /**
  35  * @author Mikhail Golubev
  36  * @author Alexey.Ivanov
  37  */
  38 public class PyIncorrectDocstringInspection extends PyBaseDocstringInspection {
  39   @NotNull
  40   @Override
  41   public Visitor buildVisitor(@NotNull ProblemsHolder holder, boolean isOnTheFly, @NotNull LocalInspectionToolSession session) {
  42     return new Visitor(holder, session) {
  43
  44       @Override
  45       protected void checkDocString(@NotNull PyDocStringOwner node) {
  46         final PyStringLiteralExpression docstringExpr = node.getDocStringExpression();
  47         if (docstringExpr != null) {
  48           checkParameters(node, docstringExpr);
  49         }
  50       }
  51
  52       private void checkParameters(@NotNull PyDocStringOwner pyDocStringOwner, @NotNull PyStringLiteralExpression node) {
  53         final String text = node.getText();
  54         if (text == null) {
  55           return;
  56         }
  57
  58         final StructuredDocString docString = DocStringUtil.parse(text, node);
  59
  60         if (docString instanceof PlainDocString) {
  61           return;
  62         }
  63
  64         if (pyDocStringOwner instanceof PyFunction) {
  65           final PyParameter[] realParams = ((PyFunction)pyDocStringOwner).getParameterList().getParameters();
  66
  67           final List<PyNamedParameter> missingParams = getMissingParams(docString, realParams);
  68           if (!missingParams.isEmpty()) {
  69             for (PyNamedParameter param : missingParams) {
  70               registerProblem(param,
  71                               PyBundle.message("INSP.missing.parameter.in.docstring", param.getName()),
  72                               new DocstringQuickFix(param, null));
  73             }
  74           }
  75           final List<Substring> unexpectedParams = getUnexpectedParams(docString, realParams);
  76           if (!unexpectedParams.isEmpty()) {
  77             for (Substring param : unexpectedParams) {
  78               final ProblemsHolder holder = getHolder();
  79
  80               if (holder != null) {
  81                 holder.registerProblem(node, param.getTextRange(),
  82                                        PyBundle.message("INSP.unexpected.parameter.in.docstring", param),
  83                                        new DocstringQuickFix(null, param.getValue()));
  84               }
  85             }
  86           }
  87         }
  88       }
  89     };
  90   }
  91
  92   @NotNull
  93   private static List<PyNamedParameter> getMissingParams(@NotNull StructuredDocString docString, @NotNull PyParameter[] realParams) {
  94     final List<PyNamedParameter> missing = new ArrayList<PyNamedParameter>();
  95     final List<String> docStringParameters = docString.getParameters();
  96     for (PyParameter p : realParams) {
  97       if (p.isSelf() || !(p instanceof PyNamedParameter)) {
  98         continue;
  99       }
 100       if (!docStringParameters.contains(p.getName())) {
 101         missing.add((PyNamedParameter)p);
 102       }
 103     }
 104     return missing;
 105   }
 106
 107   @NotNull
 108   private static List<Substring> getUnexpectedParams(@NotNull StructuredDocString docString, @NotNull PyParameter[] realParams) {
 109     final Map<String, Substring> unexpected = Maps.newHashMap();
 110
 111     for (Substring s : docString.getParameterSubstrings()) {
 112       unexpected.put(s.toString(), s);
 113     }
 114
 115     for (PyParameter p : realParams) {
 116       if (unexpected.containsKey(p.getName())) {
 117         unexpected.remove(p.getName());
 118       }
 119     }
 120     return Lists.newArrayList(unexpected.values());
 121   }
 122 }