diff --git a/.gitignore b/.gitignore index f973a20ab..0b2b7d318 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,5 @@ project.xcworkspace */xcuserdata/ ObjectiveGitTests/fixtures/Fixtures/* + +Docs/ \ No newline at end of file diff --git a/Classes/GTReference.h b/Classes/GTReference.h index 470b009f3..26fa17a42 100644 --- 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 new file mode 100755 index 000000000..9d1e9d22e --- /dev/null +++ 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 \ No newline at end of file