Repository: pandas-dev/pandas

Issue:
DOC: Add validation error when a docstring is missing
We have the script `scripts/validate_docstrings.py` that checks several formatting errors in the docstrings.

Currently, when a function, method... has no docstring at all, it fails few of the checks, but we don't have one specific to it. See for example:
```
$ ./scripts/validate_docstrings.py --prefix=pandas.Series.imag
pandas.Series.imag: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Series.imag: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Series.imag: No summary found (a short summary in a single line should be present at the beginning of the docstring)
```

What would be useful is to add a new check, that reports that the function does not have a docstring. And in the previous errors, check when the docstring is empty, and do not report them. So the previous call should report a single error with a text like `pandas.Series.imag: No docstring found`.


Discussion:
I'm working on Pandas at PyconCa sprint I'll give it a go.

Resolving patch:
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
--- a/scripts/validate_docstrings.py
+++ b/scripts/validate_docstrings.py
@@ -78,6 +78,7 @@
             '{allowed_sections}',
     'GL07': 'Sections are in the wrong order. Correct order is: '
             '{correct_sections}',
+    'GL08': 'The object does not have a docstring',
     'SS01': 'No summary found (a short summary in a single line should be '
             'present at the beginning of the docstring)',
     'SS02': 'Summary does not start with a capital letter',
@@ -545,20 +546,24 @@ def validate_pep8(self):
         yield from application.guide.stats.statistics_for('')
 
 
-def validate_one(func_name):
+def get_validation_data(doc):
     """
-    Validate the docstring for the given func_name
+    Validate the docstring.
 
     Parameters
     ----------
-    func_name : function
-        Function whose docstring will be evaluated (e.g. pandas.read_csv).
+    doc : Docstring
+        A Docstring object with the given function name.
 
     Returns
     -------
-    dict
-        A dictionary containing all the information obtained from validating
-        the docstring.
+    tuple
+        errors : list of tuple
+            Errors occurred during validation.
+        warnings : list of tuple
+            Warnings occurred during validation.
+        examples_errs : str
+            Examples usage displayed along the error, otherwise empty string.
 
     Notes
     -----
@@ -585,10 +590,13 @@ def validate_one(func_name):
     they are validated, are not documented more than in the source code of this
     function.
     """
-    doc = Docstring(func_name)
 
     errs = []
     wrns = []
+    if not doc.raw_doc:
+        errs.append(error('GL08'))
+        return errs, wrns, ''
+
     if doc.start_blank_lines != 1:
         errs.append(error('GL01'))
     if doc.end_blank_lines != 1:
@@ -706,7 +714,26 @@ def validate_one(func_name):
         for wrong_import in ('numpy', 'pandas'):
             if 'import {}'.format(wrong_import) in examples_source_code:
                 errs.append(error('EX04', imported_library=wrong_import))
+    return errs, wrns, examples_errs
+
+
+def validate_one(func_name):
+    """
+    Validate the docstring for the given func_name
 
+    Parameters
+    ----------
+    func_name : function
+        Function whose docstring will be evaluated (e.g. pandas.read_csv).
+
+    Returns
+    -------
+    dict
+        A dictionary containing all the information obtained from validating
+        the docstring.
+    """
+    doc = Docstring(func_name)
+    errs, wrns, examples_errs = get_validation_data(doc)
     return {'type': doc.type,
             'docstring': doc.clean_doc,
             'deprecated': doc.deprecated,


Test patch:
diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
--- a/scripts/tests/test_validate_docstrings.py
+++ b/scripts/tests/test_validate_docstrings.py
@@ -407,6 +407,9 @@ def sections_in_wrong_order(self):
             before Examples.
         """
 
+    def method_wo_docstrings(self):
+        pass
+
 
 class BadSummaries(object):
 
@@ -826,6 +829,8 @@ def test_bad_generic_functions(self, func):
          ('Do not import numpy, as it is imported automatically',)),
         ('BadGenericDocStrings', 'method',
          ('Do not import pandas, as it is imported automatically',)),
+        ('BadGenericDocStrings', 'method_wo_docstrings',
+         ("The object does not have a docstring",)),
         # See Also tests
         ('BadSeeAlso', 'prefix_pandas',
          ('pandas.Series.rename in `See Also` section '