PY-16987 Google and Numpy docstrings return null as parameter type if it wasn't speci...
[idea/community.git] / python / psi-api / src / com / jetbrains / python / psi / StructuredDocString.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.psi;
17
18 import com.jetbrains.python.toolbox.Substring;
19 import org.jetbrains.annotations.NotNull;
20 import org.jetbrains.annotations.Nullable;
21
22 import java.util.List;
23
24 /**
25  * @author vlan
26  */
27 public interface StructuredDocString {
28
29   String getSummary();
30   String getDescription(); // for formatter
31
32   @NotNull
33   List<String> getParameters();
34
35   /**
36    * @return all names of parameters mentioned in the docstring as substrings.
37    */
38   @NotNull
39   List<Substring> getParameterSubstrings();
40
41   /**
42    * @param paramName {@code null} can be used for unnamed parameters descriptors, e.g. in docstring following class attribute
43    * @return {@code null} if specified parameter was omitted in the docstring completely, empty string if there was place for its type, 
44    * but it was unfilled and trimmed type text otherwise.
45    */
46   @Nullable
47   String getParamType(@Nullable String paramName);
48
49   /**
50    * @param paramName {@code null} can be used for unnamed parameters descriptors, e.g. in docstring following class attribute
51    * @return {@code null} if specified parameter was omitted in the docstring completely, empty substring if there was place for its type, 
52    * but it was unfilled and trimmed type substring otherwise.
53    */
54   @Nullable
55   Substring getParamTypeSubstring(@Nullable String paramName);
56
57   /**
58    * @param paramName {@code null} can be used for unnamed parameters descriptors, e.g. in docstring following class attribute
59    */
60   @Nullable
61   String getParamDescription(@Nullable String paramName);
62   /**
63    * Keyword arguments are those arguments that usually don't exist in function signature, 
64    * but are passed e.g. via {@code **kwargs} mechanism. 
65    */
66   @NotNull
67   List<String> getKeywordArguments();
68   @NotNull
69   List<Substring> getKeywordArgumentSubstrings();
70
71   // getKeywordArgumentType(name)
72   // getKeywordArgumentTypeString(name)  
73   @Nullable
74   String getKeywordArgumentDescription(@Nullable String paramName);
75
76   /**
77    * @return {@code null} if return type was omitted in the docstring completely, empty string if there was place for its type,
78    * but it was unfilled and trimmed type text otherwise.
79    */
80   @Nullable
81   String getReturnType();
82
83   /**
84    * @return {@code null} if return type was omitted in the docstring completely, empty substring if there was place for its type,
85    * but it was unfilled and trimmed type substring otherwise.
86    */  @Nullable
87   Substring getReturnTypeSubstring();
88
89   @Nullable
90   String getReturnDescription(); // for formatter
91   @NotNull
92   List<String> getRaisedExceptions(); // for formatter
93
94   @Nullable
95   String getRaisedExceptionDescription(@Nullable String exceptionName); // for formatter
96
97   // getAttributes
98   // getAttributeSubstrings
99   // getAttributeType(name)
100   // getAttributeTypeSubstring(name)
101   @Nullable
102   String getAttributeDescription(); // for formatter
103
104   // Tags related methods
105 }