Use debugger signatures and add return declarations in PyDocStringGenerator by default
authorMikhail Golubev <mikhail.golubev@jetbrains.com>
Sun, 23 Aug 2015 21:31:32 +0000 (00:31 +0300)
committerMikhail Golubev <mikhail.golubev@jetbrains.com>
Wed, 2 Sep 2015 11:35:01 +0000 (14:35 +0300)
python/src/com/jetbrains/python/codeInsight/intentions/PyGenerateDocstringIntention.java
python/src/com/jetbrains/python/documentation/PyDocstringGenerator.java
python/src/com/jetbrains/python/editor/PythonEnterHandler.java

index d0cdeb8b370aac9910b621cc44977de5e5f974fb..882ce0a893091741152309b4af2153c828b1a132 100644 (file)
@@ -102,16 +102,7 @@ public class PyGenerateDocstringIntention extends BaseIntentionAction {
       return;
     }
     final PyDocstringGenerator docstringGenerator = new PyDocstringGenerator(docStringOwner);
-    if (docStringOwner instanceof PyFunction) {
-      docstringGenerator
-        .useTypesFromDebuggerSignature(true)
-        .addReturn()
-        .addFirstEmptyLine();
-
-      if (docStringOwner.getDocStringValue() == null) {
-        docstringGenerator.addReturn();
-      }
-    }
+    docstringGenerator.addFirstEmptyLine();
     final PyStringLiteralExpression updated = docstringGenerator.buildAndInsert().getDocStringExpression();
     if (updated != null && editor != null) {
       final int offset = updated.getTextOffset();
index 124d7753dcc2dc73e555a58dc4348948a28673e8..42e138e6918134bf2d44cecc47bb9786faa1512d 100644 (file)
@@ -49,11 +49,11 @@ public class PyDocstringGenerator {
   @NotNull
   private PyDocStringOwner myDocStringOwner;
 
-  private boolean myUseTypesFromDebuggerSignature = false;
+  private boolean myUseTypesFromDebuggerSignature = true;
   private boolean myNewMode = false; // true - generate new string, false - update existing
   private boolean myAddFirstEmptyLine = false;
   private boolean myParametersPrepared = false;
-  private boolean myGenerateReturn;
+  private boolean myAlwaysGenerateReturn;
   private String myQuotes = "\"\"\"";
 
   public PyDocstringGenerator(@NotNull PyDocStringOwner docStringOwner) {
@@ -91,9 +91,14 @@ public class PyDocstringGenerator {
     return this;
   }
 
+  /**
+   * By default return declaration is added only if function body contains return statement. Sometimes it's not possible, e.g.
+   * in  {@link com.jetbrains.python.editor.PythonEnterHandler} where unclosed docstring literal "captures" whole function body
+   * including return statements.
+   */
   @NotNull
-  public PyDocstringGenerator addReturn() {
-    myGenerateReturn = true;
+  public PyDocstringGenerator forceAddReturn() {
+    myAlwaysGenerateReturn = true;
     return this;
   }
 
@@ -136,16 +141,14 @@ public class PyDocstringGenerator {
             withParamTypedByName(paramName, type);
           }
         }
-        if (myGenerateReturn) {
-          final RaiseVisitor visitor = new RaiseVisitor();
-          final PyStatementList statementList = ((PyFunction)myDocStringOwner).getStatementList();
-          statementList.accept(visitor);
-          if (visitor.myHasReturn) {
-            // will add :return: placeholder in Sphinx/Epydoc docstrings
-            myParams.add(new DocstringParam("", null, true));
-            if (PyCodeInsightSettings.getInstance().INSERT_TYPE_DOCSTUB) {
-              withReturnValue("");
-            }
+        final RaiseVisitor visitor = new RaiseVisitor();
+        final PyStatementList statementList = ((PyFunction)myDocStringOwner).getStatementList();
+        statementList.accept(visitor);
+        if (visitor.myHasReturn || myAlwaysGenerateReturn) {
+          // will add :return: placeholder in Sphinx/Epydoc docstrings
+          myParams.add(new DocstringParam("", null, true));
+          if (PyCodeInsightSettings.getInstance().INSERT_TYPE_DOCSTUB) {
+            withReturnValue("");
           }
         }
       }
index 0df65ab46730cac300486a964eb726587d3ec4ed..1bf6fc4af41d15839cb9871bdf91245c64cc5a72 100644 (file)
@@ -262,8 +262,7 @@ public class PythonEnterHandler extends EnterHandlerDelegateAdapter {
       final int caretOffset = editor.getCaretModel().getOffset();
       final String quotes = editor.getDocument().getText(TextRange.from(caretOffset - 3, 3));
       final String docString = new PyDocstringGenerator(docOwner)
-        .addReturn()
-        .useTypesFromDebuggerSignature(true)
+        .forceAddReturn()
         .withQuotes(quotes)
         .forceNewMode()
         .buildDocString();