Complete addition of docstrings

Author: ararslan

src/Git.jl

@@ -13,7 +13,7 @@ isfile(depsjl) ? include(depsjl) : error("Git.jl not properly installed. " *
     "Please run\nPkg.build(\"Git\")")
 
 """
-    Git.dir([d])
+    Git.dir(d)
 
 Return the path to the default `.git` for the given repository directory, or the
 path to use in place of the default `.git`.
@@ -24,6 +24,12 @@ function dir(d)
     normpath(d, Base.readchomp(setenv(`$gitcmd rev-parse --git-dir`, dir=d)))
 end
 
+"""
+    Git.git([d])
+
+Return a Git command that refers to the work tree and directory given by `d`, or the
+current work tree and directory of `d` is not specified.
+"""
 git() = gitcmd
 function git(d)
     isempty(d) && return gitcmd
@@ -39,8 +45,29 @@ end
 Return a Git command from the given arguments, acting on the repository given in `dir`.
 """
 cmd(args::Cmd; dir="") = `$(git(dir)) $args`
+
+"""
+    Git.run(args; dir="", out=STDOUT)
+
+Execute the Git command from the given arguments `args` on the repository `dir`, writing
+the results to the output stream `out`.
+"""
 run(args::Cmd; dir="", out=STDOUT) = Base.run(pipeline(cmd(args,dir=dir), out))
+
+"""
+    Git.readstring(args; dir="")
+
+Read the result of the Git command using the given arguments on the given repository
+as a string.
+"""
 readstring(args::Cmd; dir="") = Base.readstring(cmd(args,dir=dir))
+
+"""
+    Git.readchomp(args; dir="")
+
+Read the result of the Git command using the given arguments on the given repository
+as a string, removing a single trailing newline if present.
+"""
 readchomp(args::Cmd; dir="") = Base.readchomp(cmd(args,dir=dir))
 
 """
@@ -71,25 +98,79 @@ function version()
     end
 end
 
+"""
+    Git.modules(args; dir="")
+
+Apply the Git command with the given arguments on the given repository to the
+configuration file `.gitmodules` and read the result as a string.
+"""
 modules(args::Cmd; dir="") = readchomp(`config -f .gitmodules $args`, dir=dir)
+
+"""
+    Git.different(verA, verB, path; dir="")
+
+Determine whether two trees are different with respect to the given path.
+"""
 different(verA::AbstractString, verB::AbstractString, path::AbstractString; dir="") =
     !success(`diff-tree --quiet $verA $verB -- $path`, dir=dir)
 
+"""
+    Git.dirty([paths]; dir="")
+
+Determine whether the paths in the given repository are dirty, i.e. contain modified but
+uncommitted tracked files.
+"""
 dirty(; dir="") = !success(`diff-index --quiet HEAD`, dir=dir)
-staged(; dir="") = !success(`diff-index --quiet --cached HEAD`, dir=dir)
-unstaged(; dir="") = !success(`diff-files --quiet`, dir=dir)
 dirty(paths; dir="") = !success(`diff-index --quiet HEAD -- $paths`, dir=dir)
+
+"""
+    Git.staged([paths]; dir="")
+
+Determine whether the paths in the given repository contain staged files.
+"""
+staged(; dir="") = !success(`diff-index --quiet --cached HEAD`, dir=dir)
 staged(paths; dir="") = !success(`diff-index --quiet --cached HEAD -- $paths`, dir=dir)
+
+"""
+    Git.unstaged([paths]; dir="")
+
+Determine whether the paths in the given repository contain unstaged files.
+"""
+unstaged(; dir="") = !success(`diff-files --quiet`, dir=dir)
 unstaged(paths; dir="") = !success(`diff-files --quiet -- $paths`, dir=dir)
 
+"""
+    Git.iscommit(name; dir="")
+
+Determine whether `name` refers to a commit in the repository `dir`. `name` can be a
+single SHA1 or a vector of SHA1s.
+"""
 iscommit(name; dir="") = success(`cat-file commit $name`, dir=dir)
+function iscommit(sha1s::Vector; dir="")
+    indexin(sha1s,split(readchomp(`log --all --format=%H`, dir=dir),"\n")).!=0
+end
+
+"""
+    Git.attached(; dir="")
+
+Determine whether HEAD is attached to a commit in the given respository.
+"""
 attached(; dir="") = success(`symbolic-ref -q HEAD`, dir=dir)
+
+"""
+    Git.branch(; dir="")
+
+Return the name of the current active branch in the given repository.
+"""
 branch(; dir="") = readchomp(`rev-parse --symbolic-full-name --abbrev-ref HEAD`, dir=dir)
+
+"""
+    Git.head(; dir="")
+
+Return the commit to which HEAD currently refers.
+"""
 head(; dir="") = readchomp(`rev-parse HEAD`, dir=dir)
 
-function iscommit(sha1s::Vector; dir="")
-    indexin(sha1s,split(readchomp(`log --all --format=%H`, dir=dir),"\n")).!=0
-end
 
 immutable State
     head::Compat.UTF8String
@@ -100,7 +181,7 @@ end
 """
     Git.snapshot(; dir="")
 
-Return a `State` object that consisting of a snapshot of the given repository.
+Return a `State` object that captures a snapshot of the given repository.
 """
 function snapshot(; dir="")
     head = readchomp(`rev-parse HEAD`, dir=dir)
@@ -118,7 +199,7 @@ function snapshot(; dir="")
 end
 
 """
-    Git.restore(s; dir="")
+    Git.restore(s::State; dir="")
 
 Restore the given repository to the state `s`.
 """