From 0b98093370099f0857ea1990d22950c5eb05cca3 Mon Sep 17 00:00:00 2001
From: Lee Dohm <lee@lee-dohm.com>
Date: Mon, 5 Jan 2015 21:32:11 -0800
Subject: [PATCH] :memo: Prevent confusion over project.contains

See https://discuss.atom.io/t/testing-for-the-existence-of-a-file/14079
---
 src/project.coffee | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/project.coffee b/src/project.coffee
index 005c23165..9a8040a22 100644
--- a/src/project.coffee
+++ b/src/project.coffee
@@ -166,9 +166,33 @@ class Project extends Model
     return fullPath if fullPath?.match(/[A-Za-z0-9+-.]+:\/\//) # leave path alone if it has a scheme
     @rootDirectory?.relativize(fullPath) ? fullPath
 
-  # Public: Returns whether the given path is inside this project.
+  # Public: Determines whether the given path (real or symbolic) is inside the
+  # project's directory.
+  #
+  # This method does not actually check if the path exists, it just checks their
+  # locations relative to each other.
+  #
+  # ## Examples
+  #
+  # Basic operation
+  #
+  # ```coffee
+  # # Project's root directory is /foo/bar
+  # project.contains('/foo/bar/baz')        # => true
+  # project.contains('/usr/lib/baz')        # => false
+  # ```
+  #
+  # Existence of the path is not required
+  #
+  # ```coffee
+  # # Project's root directory is /foo/bar
+  # fs.existsSync('/foo/bar/baz')           # => false
+  # project.contains('/foo/bar/baz')        # => true
+  # ```
   #
   # * `pathToCheck` {String} path
+  #
+  # Returns whether the path is inside the project's root directory.
   contains: (pathToCheck) ->
     @rootDirectory?.contains(pathToCheck) ? false