Addressing comments from the code review

pandas-dev · datapythonista · Oct 13, 2018 · Aug 18, 2018 · Aug 18, 2018 · Aug 18, 2018
commit 188f4a39870fb1565af8a17b731023e1c7ef3243
diff --git a/pandas/tests/scripts/test_validate_docstrings.py b/pandas/tests/scripts/test_validate_docstrings.py
@@ -490,25 +490,33 @@ def _import_path(self, klass=None, func=None):
         return base_path
 
     def test_good_class(self):
-        assert len(validate_one(self._import_path(  # noqa: F821
-            klass='GoodDocStrings'))['errors']) == 0
+        errors = validate_one(self._import_path(  # noqa: F821
+            klass='GoodDocStrings'))['errors']
+        assert isinstance(errors, list)
+        assert not errors
 
     @pytest.mark.parametrize("func", [
         'plot', 'sample', 'random_letters', 'sample_values', 'head', 'head1',
         'contains'])
     def test_good_functions(self, func):
-        assert len(validate_one(self._import_path(   # noqa: F821
-            klass='GoodDocStrings', func=func))['errors']) == 0
+        errors = validate_one(self._import_path(   # noqa: F821
+            klass='GoodDocStrings', func=func))['errors']
+        assert isinstance(errors, list)
+        assert not errors
 
     def test_bad_class(self):
-        assert len(validate_one(self._import_path(  # noqa: F821
-            klass='BadGenericDocStrings'))['errors']) > 0
+        errors = validate_one(self._import_path(  # noqa: F821
+            klass='BadGenericDocStrings'))['errors']
+        assert isinstance(errors, list)
+        assert errors
 
     @pytest.mark.parametrize("func", [
         'func', 'astype', 'astype1', 'astype2', 'astype3', 'plot', 'method'])
     def test_bad_generic_functions(self, func):
-        assert len(validate_one(self._import_path(  # noqa:F821
-            klass='BadGenericDocStrings', func=func))['errors']) > 0
+        errors = validate_one(self._import_path(  # noqa:F821
+            klass='BadGenericDocStrings', func=func))['errors']
+        assert isinstance(errors, list)
+        assert errors
 
     @pytest.mark.parametrize("klass,func,msgs", [
         # Summary tests
@@ -546,6 +554,6 @@ def test_bad_generic_functions(self, func):
                      marks=pytest.mark.xfail)
     ])
     def test_bad_examples(self, capsys, klass, func, msgs):
-        res = validate_one(self._import_path(klass=klass, func=func))  # noqa:F821
+        result = validate_one(self._import_path(klass=klass, func=func))  # noqa:F821
         for msg in msgs:
-            assert msg in ''.join(res['errors'])
+            assert msg in ' '.join(result['errors'])
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
@@ -45,6 +45,24 @@
 
 
 def get_api_items():
+    """
+    Parse api.rst file from the documentation, and extract all the functions,
+    methods, classes, attributes... This should include all pandas public API.
+
+    Yields
+    ------
+    name : str
+        The name of the object (e.g. 'pandas.Series.str.upper).
+    func : function
+        The object itself. In most cases this will be a function or method,
+        but it can also be classes, properties, cython objects...
+    section : str
+        The name of the section in the API page where the object item is
+        located.
+    subsection : str
+        The name of the subsection in the API page where the object item is
+        located.
+    """
     api_fname = os.path.join(BASE_PATH, 'doc', 'source', 'api.rst')
 
     previous_line = current_section = current_subsection = ''
@@ -177,9 +195,15 @@ def is_function_or_method(self):
 
     @property
     def source_file_name(self):
+        """
+        File name where the object is implemented (e.g. pandas/core/frame.py).
+        """
         try:
             fname = inspect.getsourcefile(self.code_obj)
         except TypeError:
+            # In some cases the object is something complex like a cython
+            # object that can't be easily introspected. An it's better to
+            # return the source code file of the object as None, than crash
             pass
         else:
             if fname:
@@ -188,9 +212,15 @@ def source_file_name(self):
 
     @property
     def source_file_def_line(self):
+        """
+        Number of line where the object is defined in its file.
+        """
         try:
             return inspect.getsourcelines(self.code_obj)[-1]
         except (OSError, TypeError):
+            # In some cases the object is something complex like a cython
+            # object that can't be easily introspected. An it's better to
+            # return the line number as None, than crash
             pass
 
     @property