[Docs] Update downloader framework docs (#914)

* Update installable

* Update Repo manager

cogs/downloader/repo_manager.py

@@ -3,7 +3,7 @@ import json
 import os
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
-from typing import Tuple, MutableMapping
+from typing import Tuple, MutableMapping, Union
 from subprocess import run as sp_run, PIPE
 from sys import executable
 import pkgutil
@@ -166,7 +166,8 @@ class Repo(RepoJSONMixin):
     async def clone(self) -> Tuple[str]:
         """
         Clones a new repo.
-        :return: List of available modules from this repo.
+
+        :return: List of available module names from this repo.
         """
         exists, path = self._existing_git_repo()
         if exists:
@@ -203,6 +204,7 @@ class Repo(RepoJSONMixin):
     async def current_branch(self) -> str:
         """
         Determines the current branch using git commands.
+
         :return: Current branch name
         """
         exists, _ = self._existing_git_repo()
@@ -226,6 +228,7 @@ class Repo(RepoJSONMixin):
     async def current_commit(self, branch: str=None) -> str:
         """
         Determines the current commit hash of the repo.
+
         :param branch: Override for repo's branch attribute
         :return: Commit hash string
         """
@@ -253,8 +256,8 @@ class Repo(RepoJSONMixin):
     async def hard_reset(self, branch: str=None) -> None:
         """
         Performs a hard reset on the current repo.
+
         :param branch: Override for repo branch attribute.
-        :return:
         """
         if branch is None:
             branch = self.branch
@@ -280,8 +283,9 @@ class Repo(RepoJSONMixin):
     async def update(self) -> (str, str):
         """
         Updates the current branch of this repo.
-        :return: Old commit hash
-        :return: New commit hash
+
+        :return: tuple of (old commit hash, new commit hash)
+        :rtype: tuple
         """
         curr_branch = await self.current_branch()
         old_commit = await self.current_commit(branch=curr_branch)
@@ -308,9 +312,11 @@ class Repo(RepoJSONMixin):
     async def install_cog(self, cog: Installable, target_dir: Path) -> bool:
         """
         Copies a cog to the target directory.
-        :param cog:
-        :param target_dir:
-        :return: bool - if installation succeeded
+
+        :param Installable cog: Cog to install.
+        :param pathlib.Path target_dir: Directory to install the cog in.
+        :return: Installation success status.
+        :rtype: bool
         """
         if cog not in self.available_cogs:
             raise DownloaderException("That cog does not exist in this repo")
@@ -326,10 +332,12 @@ class Repo(RepoJSONMixin):
     async def install_libraries(self, target_dir: Path, libraries: Tuple[Installable]=()) -> bool:
         """
         Copies all shared libraries (or a given subset) to the target
-            directory.
-        :param target_dir:
-        :param libraries: A subset of available libraries
-        :return: bool - all copies succeeded
+        directory.
+
+        :param pathlib.Path target_dir: Directory to install shared libraries to.
+        :param tuple(Installable) libraries: A subset of available libraries.
+        :return: Status of all installs.
+        :rtype: bool
         """
         if libraries:
             if not all([i in self.available_libraries for i in libraries]):
@@ -344,11 +352,13 @@ class Repo(RepoJSONMixin):
     async def install_requirements(self, cog: Installable, target_dir: Path) -> bool:
         """
         Installs the requirements defined by the requirements
-            attribute on the cog object and puts them in the given
-            target directory.
-        :param cog:
-        :param target_dir:
-        :return:
+        attribute on the cog object and puts them in the given
+        target directory.
+
+        :param Installable cog: Cog for which to install requirements.
+        :param pathlib.Path target_dir: Path to which to install requirements.
+        :return: Status of requirements install.
+        :rtype: bool
         """
         if not target_dir.is_dir():
             raise ValueError("Target directory is not a directory.")
@@ -359,10 +369,12 @@ class Repo(RepoJSONMixin):
     async def install_raw_requirements(self, requirements: Tuple[str], target_dir: Path) -> bool:
         """
         Installs a list of requirements using pip and places them into
-            the given target directory.
-        :param requirements:
-        :param target_dir:
-        :return:
+        the given target directory.
+
+        :param tuple(str) requirements: List of requirement names to install via pip.
+        :param pathlib.Path target_dir: Directory to install requirements to.
+        :return: Status of all requirements install.
+        :rtype: bool
         """
         if len(requirements) == 0:
             return True
@@ -388,7 +400,8 @@ class Repo(RepoJSONMixin):
     def available_cogs(self) -> Tuple[Installable]:
         """
         Returns a list of available cogs (not shared libraries and not hidden).
-        :return: tuple(installable)
+
+        :rtype: tuple(Installable)
         """
         # noinspection PyTypeChecker
         return tuple(
@@ -400,6 +413,8 @@ class Repo(RepoJSONMixin):
     def available_libraries(self) -> Tuple[Installable]:
         """
         Returns a list of available shared libraries in this repo.
+
+        :rtype: tuple(Installable)
         """
         # noinspection PyTypeChecker
         return tuple(
@@ -447,10 +462,12 @@ class RepoManager:
     async def add_repo(self, url: str, name: str, branch: str="master") -> Repo:
         """
         Adds a repo and clones it.
-        :param url:
-        :param name:
-        :param branch:
-        :return:
+
+        :param url: URL of git repo to clone.
+        :param name: Internal name of repo.
+        :param branch: Branch to clone.
+        :return: New repo object representing cloned repo.
+        :rtype: Repo
         """
         name = self.validate_and_normalize_repo_name(name)
         if self.does_repo_exist(name):
@@ -469,27 +486,31 @@ class RepoManager:
 
         return r
 
-    def get_repo(self, name: str) -> Repo:
+    def get_repo(self, name: str) -> Union[Repo, None]:
         """
         Returns a repo object with the given name.
+
         :param name: Repo name
-        :return: Repo object or None
+        :return: Repo object or ``None`` if repo does not exist.
+        :rtype: Union[Repo, None]
         """
         return self._repos.get(name, None)
 
     def get_all_repo_names(self) -> Tuple[str]:
         """
         Returns a tuple of all repo names
-        :return:
+
+        :rtype: tuple(str)
         """
         # noinspection PyTypeChecker
         return tuple(self._repos.keys())
 
     async def delete_repo(self, name: str):
         """
-        Deletes a repo and its' folders with the given name.
-        :param name:
-        :return:
+        Deletes a repo and its folders with the given name.
+
+        :param name: Name of the repo to delete.
+        :raises MissingGitRepo: If the repo does not exist.
         """
         repo = self.get_repo(name)
         if repo is None:
@@ -506,10 +527,11 @@ class RepoManager:
 
     async def update_all_repos(self) -> MutableMapping[Repo, Tuple[str, str]]:
         """
-        Calls repo.update() on all repos, returns a mapping of repos
-            that received new commits to a tuple containing old and
-            new commit hashes.
+        Calls :py:meth:`Repo.update` on all repos.
+
         :return:
+            A mapping of :py:class:`Repo` objects that received new commits to a tuple containing old and
+            new commit hashes.
         """
         ret = {}
         for _, repo in self._repos.items():