Update docstrings

Author: stsewd

readthedocs/rtd_tests/utils.py

@@ -60,15 +60,15 @@ def make_test_git():
     # URL are not allowed and using a real URL will require Internet to clone
     # the repo
     check_output(['git', 'checkout', '-b', 'submodule', 'master'], env=env)
-    add_submodule_without_cloning(
+    add_git_submodule_without_cloning(
         directory, 'foobar', 'https://foobar.com/git'
     )
     check_output(['git', 'add', '.'], env=env)
     check_output(['git', 'commit', '-m"Add submodule"'], env=env)
 
     # Add an invalid submodule URL in the invalidsubmodule branch
     check_output(['git', 'checkout', '-b', 'invalidsubmodule', 'master'], env=env)
-    add_submodule_without_cloning(
+    add_git_submodule_without_cloning(
         directory, 'invalid', '[email protected]:rtfd/readthedocs.org.git'
     )
     check_output(['git', 'add', '.'], env=env)
@@ -80,12 +80,19 @@ def make_test_git():
 
 
 @restoring_chdir
-def add_submodule_without_cloning(directory, submodule, url):
+def add_git_submodule_without_cloning(directory, submodule, url):
     """
     Add a submodule without cloning it.
 
     We write directly to the git index, more details in:
     https://stackoverflow.com/a/37378302/2187091
+
+    :param directory: The directory where the git repo is
+    :type directory: str
+    :param submodule: The name of the submodule to be created
+    :type submodule: str
+    :param url: The url where the submodule points to
+    :type url: str
     """
     env = environ.copy()
     env['GIT_DIR'] = pjoin(directory, '.git')

readthedocs/vcs_support/backends/git.py

@@ -96,13 +96,16 @@ def validate_submodules(self, config):
 
         :returns: tuple(bool, list)
 
-        Returns true if all required submodules URLs are valid.
+        Returns `True` if all required submodules URLs are valid.
         Returns a list of all required submodules:
         - Include is `ALL`, returns all submodules avaliable.
         - Include is a list, returns just those.
         - Exclude is `ALL` - this should never happen.
         - Exlude is a list, returns all avaliable submodules
           but those from the list.
+
+        Returns `False` if at least one submodule is invalid.
+        Returns the list of invalid submodules.
         """
         repo = git.Repo(self.working_dir)
         submodules = {