350bba6f906cbba72ff4d4dd59268764d3deca1e
[idea/community.git] / 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 }