Can specify a default docstring type for when the check cannot guess the type (#2340)

Close #1169

3 files changed, 41 insertions, 7 deletions

diff --git a/ChangeLog b/ChangeLog
index e53e250cf..836cb4421 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -16,6 +16,10 @@ Release date: |TBA|
 
       Close #2030
 
+   * Can specify a default docstring type for when the check cannot guess the type
+
+      Close #1169
+
 
 What's New in Pylint 1.9.3?
 ===========================
diff --git a/pylint/extensions/_check_docs_utils.py b/pylint/extensions/_check_docs_utils.py
index 594bd860e..ff8c1e5b2 100644
--- a/pylint/extensions/_check_docs_utils.py
+++ b/pylint/extensions/_check_docs_utils.py
@@ -145,14 +145,15 @@ def possible_exc_types(node):
         return set()
 
 
-def docstringify(docstring):
+def docstringify(docstring, default_type='default'):
     for docstring_type in [SphinxDocstring, EpytextDocstring,
                            GoogleDocstring, NumpyDocstring]:
         instance = docstring_type(docstring)
         if instance.is_valid():
             return instance
 
-    return Docstring(docstring)
+    docstring_type = DOCSTRING_TYPES.get(default_type, Docstring)
+    return docstring_type(docstring)
 
 
 class Docstring(object):
@@ -717,3 +718,16 @@ class NumpyDocstring(GoogleDocstring):
     @staticmethod
     def _is_section_header(line):
         return bool(re.match(r'\s*-+$', line))
+
+
+DOCSTRING_TYPES = {
+    'sphinx': SphinxDocstring,
+    'epytext': EpytextDocstring,
+    'google': GoogleDocstring,
+    'numpy': NumpyDocstring,
+    'default': Docstring,
+}
+"""A map of the name of the docstring type to its class.
+
+:type: dict(str, type)
+"""
diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py
index b5df38882..14287a9ff 100644
--- a/pylint/extensions/docparams.py
+++ b/pylint/extensions/docparams.py
@@ -123,6 +123,12 @@ class DocstringParameterChecker(BaseChecker):
                  'help': 'Whether to accept totally missing yields '
                          'documentation in the docstring of a generator.'
                 }),
+               ('default-docstring-type',
+                {'type': 'choice', 'default': 'default',
+                 'choices': list(utils.DOCSTRING_TYPES),
+                 'help': 'If the docstring type cannot be guessed '
+                         'the specified docstring type will be used.'
+                }),
               )
 
     priority = -2
@@ -136,7 +142,9 @@ class DocstringParameterChecker(BaseChecker):
         :param node: Node for a function or method definition in the AST
         :type node: :class:`astroid.scoped_nodes.Function`
         """
-        node_doc = utils.docstringify(node.doc)
+        node_doc = utils.docstringify(
+            node.doc, self.config.default_docstring_type,
+        )
         self.check_functiondef_params(node, node_doc)
         self.check_functiondef_returns(node, node_doc)
         self.check_functiondef_yields(node, node_doc)
@@ -146,7 +154,9 @@ class DocstringParameterChecker(BaseChecker):
         if node.name in self.constructor_names:
             class_node = checker_utils.node_frame_class(node)
             if class_node is not None:
-                class_doc = utils.docstringify(class_node.doc)
+                class_doc = utils.docstringify(
+                    class_node.doc, self.config.default_docstring_type,
+                )
                 self.check_single_constructor_params(class_doc, node_doc, class_node)
 
                 # __init__ or class docstrings can have no parameters documented
@@ -206,7 +216,9 @@ class DocstringParameterChecker(BaseChecker):
             if property_:
                 func_node = property_
 
-        doc = utils.docstringify(func_node.doc)
+        doc = utils.docstringify(
+            func_node.doc, self.config.default_docstring_type,
+        )
         if not doc.is_valid():
             if doc.doc:
                 self._handle_no_raise_doc(expected_excs, func_node)
@@ -224,7 +236,9 @@ class DocstringParameterChecker(BaseChecker):
         if not isinstance(func_node, astroid.FunctionDef):
             return
 
-        doc = utils.docstringify(func_node.doc)
+        doc = utils.docstringify(
+            func_node.doc, self.config.default_docstring_type,
+        )
         if not doc.is_valid() and self.config.accept_no_return_doc:
             return
 
@@ -249,7 +263,9 @@ class DocstringParameterChecker(BaseChecker):
         if not isinstance(func_node, astroid.FunctionDef):
             return
 
-        doc = utils.docstringify(func_node.doc)
+        doc = utils.docstringify(
+            func_node.doc, self.config.default_docstring_type,
+        )
         if not doc.is_valid() and self.config.accept_no_yields_doc:
             return