libgit2 · tiennou · Jul 3, 2013 · Jul 3, 2013
diff --git a/.gitignore b/.gitignore
@@ -22,3 +22,5 @@ project.xcworkspace
 */xcuserdata/
 
 ObjectiveGitTests/fixtures/Fixtures/*
+
+Docs/
diff --git a/Classes/GTReference.h b/Classes/GTReference.h
@@ -33,28 +33,60 @@ typedef enum {
 } GTReferenceErrorCode;
 
 typedef enum {
-	GTReferenceTypesOid = GIT_REF_OID,				/** A reference which points at an object id */
-	GTReferenceTypesSymbolic = GIT_REF_SYMBOLIC,	/** A reference which points at another reference */
+	GTReferenceTypesOid = GIT_REF_OID,				/* A reference which points at an object id */
+	GTReferenceTypesSymbolic = GIT_REF_SYMBOLIC,	/* A reference which points at another reference */
 	GTReferenceTypesListAll = GIT_REF_LISTALL,
 } GTReferenceTypes;
 
 @class GTRepository;
 
-
+/**
+ * A reference
+ */
 @interface GTReference : NSObject
 
+/** @name Properties */
+
+/// The repository this reference belongs to
 @property (nonatomic, readonly, strong) GTRepository *repository;
+
+/// The type of the reference
 @property (nonatomic, readonly) NSString *type;
+
+/// The underlying git_oid object
 @property (nonatomic, readonly) const git_oid *git_oid;
+
+/// The underlying GTOID object
 @property (nonatomic, strong, readonly) GTOID *OID;
 
-// Whether this is a remote-tracking branch.
+/// Whether this is a remote-tracking branch.
 @property (nonatomic, readonly, getter = isRemote) BOOL remote;
 
-// The reflog for the reference.
+/// The reflog for the reference.
 @property (nonatomic, readonly, strong) GTReflog *reflog;
 
-// Convenience initializers
+/// The name of the reference.
+@property (nonatomic, readonly, copy) NSString *name;
+
+/// The target to which the reference points.
+@property (nonatomic, readonly, copy) NSString *target;
+
+/// The underlying `git_reference` object.
+- (git_reference *)git_reference __attribute__((objc_returns_inner_pointer));
+
+/** @name Convenience initializers */
+
+/**
+ * Lookups a reference in a given repository
+ *
+ * This can be used to resolve a reference from its name
+ *
+ * @param refName	The reference name to look up
+ * @param theRepo	The repository to search in
+ * @param error		An error if one occurred
+ *
+ * @return Returns a new reference for the name passed, or nil if the reference couldn't be resolved
+ */
 + (id)referenceByLookingUpReferencedNamed:(NSString *)refName inRepository:(GTRepository *)theRepo error:(NSError **)error;
 - (id)initByLookingUpReferenceNamed:(NSString *)refName inRepository:(GTRepository *)theRepo error:(NSError **)error;
 
@@ -66,58 +98,61 @@ typedef enum {
 
 - (id)initWithGitReference:(git_reference *)ref repository:(GTRepository *)repository;
 
-// The underlying `git_reference` object.
-- (git_reference *)git_reference __attribute__((objc_returns_inner_pointer));
-
-// The target to which the reference points.
-@property (nonatomic, readonly, copy) NSString *target;
-
-// Updates the on-disk reference to point to the target and returns the updated
-// reference.
-//
-// Note that this does *not* change the receiver's target.
-//
-// newTarget - The target for the new reference. Cannot be nil.
-// error     - The error if one occurred.
-//
-// Returns the updated reference, or nil if an error occurred.
+/** @name Reference manipulation */
+
+/**
+ * Updates the on-disk reference to point to the target and returns the updated
+ * reference.
+ *
+ * Note that this does *not* change the receiver's target.
+ *
+ * @param newTarget The target for the new reference. Cannot be nil.
+ * @param error		The error if one occurred.
+ *
+ * @return Returns the updated reference, or nil if an error occurred.
+ */
 - (GTReference *)referenceByUpdatingTarget:(NSString *)newTarget error:(NSError **)error;
 
-// The name of the reference.
-@property (nonatomic, readonly, copy) NSString *name;
-
-// Updates the on-disk reference to the name and returns the renamed reference.
-//
-// Note that this does *not* change the receiver's name.
-//
-// newName - The new name for the reference. Cannot be nil.
-// error   - The error if one occurred.
-//
-// Returns the renamed reference, or nil if an error occurred.
+/**
+ * Updates the on-disk reference to the name and returns the renamed reference.
+ *
+ * Note that this does *not* change the receiver's name.
+ *
+ * @param newName	The new name for the reference. Cannot be nil.
+ * @param error		The error if one occurred.
+ *
+ * @return Returns the renamed reference, or nil if an error occurred.
+ */
 - (GTReference *)referenceByRenaming:(NSString *)newName error:(NSError **)error;
 
-// Delete this reference.
-//
-// error - The error if one occurred.
-//
-// Returns whether the deletion was successful.
+/**
+ * Delete this reference.
+ *
+ * @param error The error if one occurred.
+ *
+ * @return Returns whether the deletion was successful.
+ */
 - (BOOL)deleteWithError:(NSError **)error;
 
-// Resolve this reference as a symbolic ref
-//
-// error(out) - will be filled if an error occurs
-//
-// returns the peeled GTReference or nil if an error occurred.
+/**
+ * Resolve this reference as a symbolic ref
+ *
+ * @param error will be filled if an error occurs
+ *
+ * @return returns the peeled GTReference or nil if an error occurred.
+ */
 - (GTReference *)resolvedReferenceWithError:(NSError **)error;
 
-// Reload the reference from disk.
-//
-// error - The error if one occurred.
-//
-// Returns the reloaded reference, or nil if an error occurred.
+/**
+ * Reload the reference from disk.
+ *
+ * @param error The error if one occurred.
+ *
+ * @return Returns the reloaded reference, or nil if an error occurred.
+ */
 - (GTReference *)reloadedReferenceWithError:(NSError **)error;
 
-// An error indicating that the git_reference is no longer valid.
+/// An error indicating that the git_reference is no longer valid.
 + (NSError *)invalidReferenceError;
 
 @end
diff --git a/script/build_docs b/script/build_docs
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+PATH=$PATH:/usr/local/bin
+
+SEARCH_PATHS="Classes"
+TARGET_BUILD_DIR=${TARGET_BUILD_DIR:-$(pwd)}
+
+appledoc \
+ --project-name "Objective-Git" \
+ --project-company "Objective-Git" \
+ --company-id com.objective-git \
+ --output "$TARGET_BUILD_DIR/Docs" \
+ --logformat xcode \
+ --exit-threshold 2 \
+ --docset-feed-url "http://objective-git.com/documentation/%DOCSETATOMFILENAME" \
+ --docset-package-url "http://objective-git.com/documentation/%DOCSETPACKAGEFILENAME" \
+ --publish-docset \
+ --print-settings \
+ --keep-intermediate-files \
+ --keep-undocumented-members \
+ --keep-undocumented-objects \
+$SEARCH_PATHS
Original file line number	Diff line number	Diff line change
Expand Up		@@ -22,3 +22,5 @@ project.xcworkspace
		*/xcuserdata/

		ObjectiveGitTests/fixtures/Fixtures/*

		Docs/