Reformat Git comments

src/git.coffee

@@ -7,20 +7,26 @@ GitUtils = require 'git-utils'
 
 # Public: Represents the underlying git operations performed by Atom.
 #
-# Ultimately, this is an overlay to the native [git-utils](https://github.com/atom/node-git) module.
+# This class shouldn't be instantiated directly but instead by accessing the
+# global project instance and calling `getRepo()`.
+#
+# ## Example
+#
+# ```coffeescript
+# git = global.project.getRepo()
+# console.log git.getOriginUrl()
+# ```
 module.exports =
 class Git
   _.extend @prototype, Subscriber
   _.extend @prototype, EventEmitter
 
-  ### Public ###
-  # Creates a new `Git` instance.
+  # Private: Creates a new `Git` instance.
   #
-  # path - The git repository to open
-  # options - A hash with one key:
-  #           refreshOnWindowFocus: A {Boolean} that identifies if the windows should refresh
-  #
-  # Returns a new {Git} object.
+  # * path: The path to the git repository to open
+  # * options:
+  #    + refreshOnWindowFocus:
+  #      A Boolean that identifies if the windows should refresh
   @open: (path, options) ->
     return null unless path
     try
@@ -40,13 +46,12 @@ class Git
   upstream: null
   statusTask: null
 
-  ### Internal ###
-
-  # Creates a new `Git` object.
+  # Private: Creates a new `Git` object.
   #
-  # path - The {String} representing the path to your git working directory
-  # options - A hash with the following keys:
-  #           refreshOnWindowFocus: If `true`, {#refreshIndex} and {#refreshStatus} are called on focus
+  # * path: The {String} representing the path to your git working directory
+  # * options:
+  #    + refreshOnWindowFocus: If `true`, {#refreshIndex} and {#refreshStatus}
+  #      are called on focus
   constructor: (path, options={}) ->
     @repo = GitUtils.open(path)
     unless @repo?
@@ -69,6 +74,7 @@ class Git
       @subscribe buffer, 'saved', bufferStatusHandler
       @subscribe buffer, 'reloaded', bufferStatusHandler
 
+  # Private:
   destroy: ->
     if @statusTask?
       @statusTask.terminate()
@@ -80,35 +86,28 @@ class Git
 
     @unsubscribe()
 
-  ### Public ###
-
-  # Retrieves the git repository.
-  #
-  # Returns a new `Repository`.
+  # Private: Returns the corresponding {Repository}
   getRepo: ->
     unless @repo?
       throw new Error("Repository has been destroyed")
     @repo
 
-  # Reread the index to update any values that have changed since the last time the index was read.
+  # Public: Reread the index to update any values that have changed since the
+  # last time the index was read.
   refreshIndex: -> @getRepo().refreshIndex()
 
-  # Retrieves the path of the repository.
-  #
-  # Returns a {String}.
+  # Public: Returns the path of the repository.
   getPath: ->
     @path ?= fsUtils.absolute(@getRepo().getPath())
 
-  # Retrieves the working directory of the repository.
-  #
-  # Returns a {String}.
+  # Public: Returns the working directory of the repository.
   getWorkingDirectory: -> @getRepo().getWorkingDirectory()
 
-  # Retrieves the status of a single path in the repository.
+  # Public: Returns the status of a single path in the repository.
   #
-  # path - An {String} defining a relative path
+  # * path: A String defining a relative path
   #
-  # Returns a {Number}.
+  # Returns a {Number}, FIXME representing what?
   getPathStatus: (path) ->
     currentPathStatus = @statuses[path] ? 0
     pathStatus = @getRepo().getStatus(@relativize(path)) ? 0
@@ -120,57 +119,35 @@ class Git
       @trigger 'status-changed', path, pathStatus
     pathStatus
 
-  # Identifies if a path is ignored.
-  #
-  # path - The {String} path to check
-  #
-  # Returns a {Boolean}.
+  # Public: Determines if the given path is ignored.
   isPathIgnored: (path) -> @getRepo().isIgnored(@relativize(path))
 
-  # Identifies if a value represents a status code.
-  #
-  # status - The code {Number} to check
-  #
-  # Returns a {Boolean}.
+  # Public: Determine if the given status indicates modification.
   isStatusModified: (status) -> @getRepo().isStatusModified(status)
 
-  # Identifies if a path was modified.
-  #
-  # path - The {String} path to check
-  #
-  # Returns a {Boolean}.
+  # Public: Determine if the given path is modified.
   isPathModified: (path) -> @isStatusModified(@getPathStatus(path))
 
-  # Identifies if a status code represents a new path.
-  #
-  # status - The code {Number} to check
-  #
-  # Returns a {Boolean}.
+  # Public: Determine if the given status indicates a new path.
   isStatusNew: (status) -> @getRepo().isStatusNew(status)
 
-  # Identifies if a path is new.
-  #
-  # path - The {String} path to check
-  #
-  # Returns a {Boolean}.
+  # Public: Determine if the given path is new.
   isPathNew: (path) -> @isStatusNew(@getPathStatus(path))
 
-  # Makes a path relative to the repository's working directory.
-  #
-  # path - The {String} path to convert
-  #
-  # Returns a {String}.
+  # Public: Makes a path relative to the repository's working directory.
   relativize: (path) -> @getRepo().relativize(path)
 
-  # Retrieves a shortened version of the HEAD reference value.
+  # Public: Retrieves a shortened version of the HEAD reference value.
   #
-  # This removes the leading segments of `refs/heads`, `refs/tags`, or `refs/remotes`.
-  # It also shortens the SHA-1 of a detached `HEAD` to 7 characters.
+  # This removes the leading segments of `refs/heads`, `refs/tags`, or
+  # `refs/remotes`.  It also shortens the SHA-1 of a detached `HEAD` to 7
+  # characters.
   #
-  # Returns a {String}.
+  # Returns a String.
   getShortHead: -> @getRepo().getShortHead()
 
-  # Restore the contents of a path in the working directory and index to the version at `HEAD`.
+  # Public: Restore the contents of a path in the working directory and index
+  # to the version at `HEAD`.
   #
   # This is essentially the same as running:
   # ```
@@ -178,7 +155,7 @@ class Git
   # git checkout HEAD -- <path>
   # ```
   #
-  # path - The {String} path to checkout
+  # path - The String path to checkout
   #
   # Returns a {Boolean} that's `true` if the method was successful.
   checkoutHead: (path) ->
@@ -186,27 +163,32 @@ class Git
     @getPathStatus(path) if headCheckedOut
     headCheckedOut
 
-  # Retrieves the number of lines added and removed to a path.
+  # Public: Retrieves the number of lines added and removed to a path.
   #
-  # This compares the working directory contents of the path to the `HEAD` version.
+  # This compares the working directory contents of the path to the `HEAD`
+  # version.
   #
-  # path - The {String} path to check
+  # * path:
+  #   The String path to check
   #
-  # Returns an object with two keys, `added` and `deleted`. These will always be greater than 0.
+  # Returns an object with two keys, `added` and `deleted`. These will always
+  # be greater than 0.
   getDiffStats: (path) -> @getRepo().getDiffStats(@relativize(path))
 
-  # Identifies if a path is a submodule.
+  # Public: Identifies if a path is a submodule.
   #
-  # path - The {String} path to check
+  # * path:
+  #   The String path to check
   #
   # Returns a {Boolean}.
   isSubmodule: (path) -> @getRepo().isSubmodule(@relativize(path))
 
-  # Retrieves the status of a directory.
+  # Public: Retrieves the status of a directory.
   #
-  # path - The {String} path to check
+  # * path:
+  #   The String path to check
   #
-  # Returns a {Number} representing the status.
+  # Returns a Number representing the status.
   getDirectoryStatus: (directoryPath)  ->
     directoryPath = "#{directoryPath}/"
     directoryStatus = 0
@@ -214,28 +196,37 @@ class Git
       directoryStatus |= status if path.indexOf(directoryPath) is 0
     directoryStatus
 
-  # Retrieves the line diffs comparing the `HEAD` version of the given path and the given text.
+  # Public: Retrieves the line diffs comparing the `HEAD` version of the given
+  # path and the given text.
   #
-  # This is similar to the commit numbers reported by `git status` when a remote tracking branch exists.
+  # This is similar to the commit numbers reported by `git status` when a
+  # remote tracking branch exists.
   #
-  # path - The {String} path (relative to the repository)
-  # text - The {String} to compare against the `HEAD` contents
+  # * path:
+  #   The String path (relative to the repository)
+  # * text:
+  #   The String to compare against the `HEAD` contents
   #
-  # Returns an object with two keys, `ahead` and `behind`. These will always be greater than zero.
+  # Returns an object with two keys, `ahead` and `behind`. These will always be
+  # greater than zero.
   getLineDiffs: (path, text) -> @getRepo().getLineDiffs(@relativize(path), text)
 
+  # Public: Returns the git configuration value specified by the key.
   getConfigValue: (key) -> @getRepo().getConfigValue(key)
 
+  # Public: Returns the origin url of the repository.
   getOriginUrl: -> @getConfigValue('remote.origin.url')
 
+  # Public: ?
   getReferenceTarget: (reference) -> @getRepo().getReferenceTarget(reference)
 
+  # Public: ?
   getAheadBehindCount: (reference) -> @getRepo().getAheadBehindCount(reference)
 
+  # Public: ?
   hasBranch: (branch) -> @getReferenceTarget("refs/heads/#{branch}")?
 
-  ### Internal ###
-
+  # Private:
   refreshStatus: ->
     @statusTask = Task.once 'repository-status-handler', @getPath(), ({statuses, upstream}) =>
       statusesUnchanged = _.isEqual(statuses, @statuses) and _.isEqual(upstream, @upstream)