Merge pull request #11166 from atom/when-in-rome

Note where GitRepositoryAsync deviates from its synchronous predecessor

src/git-repository-async.js

@@ -15,6 +15,12 @@ const submoduleMode = 57344 // TODO: compose this from libgit2 constants
 // Just using this for _.isEqual and _.object, we should impl our own here
 import _ from 'underscore-plus'
 
+// For the most part, this class behaves the same as `GitRepository`, with a few
+// notable differences:
+//   * Errors are generally propagated out to the caller instead of being
+//     swallowed within `GitRepositoryAsync`.
+//   * Methods accepting a path shouldn't be given a null path, unless it is
+//     specifically allowed as noted in the method's documentation.
 export default class GitRepositoryAsync {
   static open (path, options = {}) {
     // QUESTION: Should this wrap Git.Repository and reject with a nicer message?