From 037f32c8ccba2e64def85c2d3bd8faa4621b1e4b Mon Sep 17 00:00:00 2001
From: "Mr. Outis" <mroutis@protonmail.com>
Date: Thu, 23 May 2019 16:16:02 -0700
Subject: [PATCH] docs: add some docstrings about computing status (#2048)

---
 dvc/remote/base.py   | 11 +++++++++++
 dvc/repo/__init__.py | 41 +++++++++++++++++++++++++++++++++++++++++
 dvc/repo/status.py   | 26 ++++++++++++++++++++++++++
 3 files changed, 78 insertions(+)

diff --git a/dvc/remote/base.py b/dvc/remote/base.py
index a597521ae..30f13a8f4 100644
--- a/dvc/remote/base.py
+++ b/dvc/remote/base.py
@@ -503,6 +503,17 @@ class RemoteBASE(object):
         return removed
 
     def changed_cache_file(self, checksum):
+        """Compare the given checksum with the (corresponding) actual one.
+
+        - Use `State` as a cache for computed checksums
+            + The entries are invalidated by taking into account the following:
+                * mtime
+                * inode
+                * size
+                * checksum
+
+        - Remove the file from cache if it doesn't match the actual checksum
+        """
         cache_info = self.checksum_to_path_info(checksum)
         actual = self.get_checksum(cache_info)
 
diff --git a/dvc/repo/__init__.py b/dvc/repo/__init__.py
index e50b3eb1d..94cb0e879 100644
--- a/dvc/repo/__init__.py
+++ b/dvc/repo/__init__.py
@@ -176,6 +176,26 @@ class Repo(object):
     def _collect_dir_cache(
         self, out, branch=None, remote=None, force=False, jobs=None
     ):
+        """Get a list of `info`s retaled to the given directory.
+
+        - Pull the directory entry from the remote cache if it was changed.
+
+        Example:
+
+            Given the following commands:
+
+            $ echo "foo" > directory/foo
+            $ echo "bar" > directory/bar
+            $ dvc add directory
+
+            It will return something similar to the following list:
+
+            [
+                { 'path': 'directory',     'md5': '168fd6761b9c.dir', ... },
+                { 'path': 'directory/foo', 'md5': 'c157a79031e1', ... },
+                { 'path': 'directory/bar', 'md5': 'd3b07384d113', ... },
+            ]
+        """
         info = out.dumpd()
         ret = [info]
         r = out.remote
@@ -216,6 +236,13 @@ class Repo(object):
     def _collect_used_cache(
         self, out, branch=None, remote=None, force=False, jobs=None
     ):
+        """Get a dumpd of the given `out`, with an entry including the branch.
+
+        The `used_cache` of an output is no more than its `info`.
+
+        In case that the given output is a directory, it will also
+        include the `info` of its files.
+        """
         if not out.use_cache or not out.info:
             if not out.info:
                 logger.warning(
@@ -252,6 +279,20 @@ class Repo(object):
         jobs=None,
         recursive=False,
     ):
+        """Get the stages related to the given target and collect
+        the `info` of its outputs.
+
+        This is useful to know what files from the cache are _in use_
+        (namely, a file described as an output on a stage).
+
+        The scope is, by default, the working directory, but you can use
+        `all_branches` or `all_tags` to expand scope.
+
+        Returns:
+            A dictionary with Schemes (representing output's location) as keys,
+            and a list with the outputs' `dumpd` as values.
+        """
+
         cache = {}
         cache["local"] = []
         cache["s3"] = []
diff --git a/dvc/repo/status.py b/dvc/repo/status.py
index 24bc17fc6..e9425d4d8 100644
--- a/dvc/repo/status.py
+++ b/dvc/repo/status.py
@@ -35,6 +35,32 @@ def _cloud_status(
     with_deps=False,
     all_tags=False,
 ):
+    """Returns a dictionary with the files that are new or deleted.
+
+    - new: Remote doesn't have the file
+    - deleted: File is no longer in the local cache
+
+    Example:
+            Given the following commands:
+
+            $ echo "foo" > foo
+            $ echo "bar" > bar
+            $ dvc add foo bar
+            $ dvc status -c
+
+            It will return something like:
+
+            { "foo": "new", "bar": "new" }
+
+            Now, after pushing and removing "bar" from the local cache:
+
+            $ dvc push
+            $ rm .dvc/cache/c1/57a79031e1c40f85931829bc5fc552
+
+            The result would be:
+
+            { "bar": "deleted" }
+    """
     import dvc.remote.base as cloud
 
     used = self.used_cache(