 
 	transformTo: (refName) ->
 		###
-		 * Transforms provided refName to destination, provided it matches src pattern.
-		 * @param {String} refName
-		 * @throws {Error} if refName doesn't match src pattern.
-		 * @return {String} transformed reference name.
+		Transforms given `refName` to destination, provided it matches src
+		pattern, and throws an error if it doesn't.
 		###
 		throw new Error "Ref doesn't match src." if not @matchesSrc refName
 		return "#{@dst[0...-2]}#{refName[(@src.length-2)..]}"
 
 	transformFrom: (refName) ->
 		###
-		 * Transforms provided refName from destination back to source, provided it
-		 * matches dst pattern. This is the reverse of {@link #transformTo}.
-		 * @param {String} refName
-		 * @throws {Error} if refName doesn't match dst pattern.
-		 * @return {String} (un?)transformed reference name.
+		Transforms provided refName from destination back to source, provided it
+		matches dst pattern, and throws an Error if it doesn't. This is the
+		reverse of :func:`gitteh::Refspec.transformTo`
 		###
 		throw new Error "Ref doesn't match dst." if not @matchesDst refName
 		return "#{@src[0...-2]}#{refName[(@dst.length-2)..]}"
 
+
 Gitteh.Commit = class Commit
 	###
-	A commit made by a author (and optional different committer) with a message,
-	a {Tree} and zero or more parent {@link Commit} objects.
-	@property {String} id object id of this Commit.
-	@property {String} treeId object id of {@link Tree} for this Commit.
-	@property {Commit[]} parents parent Commits of this Commit (more than one 
-	means a merge-commit).
-	@property {String} message
-	@property {String} messageEncoding
-	@property {Signature} author
-	@property {Signature} committer
-	###
+	Commits, made by an author, and an optional different committer, contain a
+	message, an associated :class:`gitteh::Tree`, and zero or more parent
+	:class:`gitteh::Commit` objects. Zero parents generally indicate the initial 
+	commit for the repository. More than one parent commits indicate a merge
+	commit.
+
+	Properties:
+
+	* **id**: *(String)* OID of this commit (SHA1 hash)
+	* **treeId**: *(String)* OID of associated :class:`gitteh::Tree`
+	* **parents**: *(String[]) list of parent commit OIDs
+	* **message**: *(String)*
+	* **messageEncoding**: *(???)* ??? TODO:
+	* **author**: (:class:`gitteh::Signature`)
+	* **committer**: (:class:`gitteh::Signature`)
+	###
+
 	constructor: (@repository, obj) ->
 		obj.author = new Signature obj.author
 		obj.committer = new Signature obj.committer

			return o
	}

Gitteh.Signature = class Signature
	###
	Contains the name/email/time for a :class:`gitteh::Commit` author/committer
	or :class:`gitteh::Tag` tagger.

	Signatures contain the following properties:

	* **name**: (String)
	* **email**: (String)
	* **time**: (Date)
	* **offset**: (Number) timezone offset in seconds from GMT.
	###
	constructor: (obj) ->
		_immutable(@, obj)
			.set("name")

		_immutable(@, {src, dst})
			.set("src")
			.set("dst")

	matchesSrc: (refName) ->
		###
		Returns true/false if given `refName` matches source of this Refspec.
		###
		_priv = _getPrivate @
		return false if refName.length <= _priv.srcRoot.length
