Commits

Jens Alfke committed b776363

Added doc-comments to the classes, to help other people make sense of the code.

  • Participants
  • Parent commits a62138f

Comments (0)

Files changed (17)

File Source/HgConfigFile.h

 #import <Cocoa/Cocoa.h>
 
 
-/** Represents a Mercurial configuration file, such as ~/.hgrc or the .hg/hgrc file in every repository. */
+/** Represents a Mercurial configuration file, such as ~/.hgrc or the .hg/hgrc file in 
+    every repository. Knows how to parse it into "stanzas" of key/value pairs. */
 @interface HgConfigFile : NSObject
 {
     NSString *_path;
 
 - (id) initWithFile: (NSString*)path;
 
+/** Returns a shared instance representing ~/.hgrc. */
 + (HgConfigFile*) userConfigFile;
 
+/** Re-reads the file if it's changed. */
 - (void) sync;
 
 - (NSDictionary*) valueForStanza: (NSString*)name;

File Source/HgDir.h

 #import "HgFile.h"
 
 
+/** A directory in a repository, as of a single revision. */
 @interface HgDir :HgFile
 {
     HgRevision *_revision;

File Source/HgFile.h

 } HgStatus;
 
 
+/** A single revision of a single file in a repository. */
 @interface HgFile : NSObject
 {
     HgDir *_dir;

File Source/HgLogOperation.h

 @class HgFile, HgRepository, HgRevision;
 
 
+/** Runs an "hg log" command and parses the output into an array of HgRevision objects. */
 @interface HgLogOperation : HgOperation
 {
     HgRepository *_repository;

File Source/HgOperation.h

 @class HgDir;
 
 
+/** An HgTask specialized for running the 'hg' command. */
 @interface HgOperation : HgTask 
 {
     NSString *_subcommand;

File Source/HgProject.h

 @class HgRepository;
 
 
-/** A "Project" is a collection of repositories with a common ancestry, used for a particular project. */
+/** A "Project" is a collection of repositories with a common ancestry.
+    For example, for one project you might have local "release" and "experimental" repositories,
+    a backup one on your web-host, and a public one on Bitbucket.
+    This class doesn't relate diectly to the Mercurial command-set;
+    it's used by the ProjectsController as the model for the Projects window. */
 @interface HgProject : NSObject <NSCoding>
 {
     NSString *_name;

File Source/HgRepository.h

 @class HgConfigFile, HgRevision, HgUncommittedRevision, HgOperation, DirectoryWatcher;
 
 
+/** The three types of repo transfers: pull, push and clone. */
 typedef enum {
     kHgPull,
     kHgPush,
     kHgClone
 } HgTransferOp;
 
+/** Option flags for clone/push/pull operations */
 enum {
     kHgUpdateAfterwards     = 0x01,     // pull, clone
     kHgForceTransfer        = 0x02,     // pull, push
 typedef UInt32 HgTransferOptions;
 
 
+/** A Mercurial repository. */
 @interface HgRepository : NSObject
 {
     NSString *_absolutePath;

File Source/HgRevision.h

 
 
 
-
+/** A specific revision in a repository. */
 @interface HgRevision : NSObject <NSCopying>
 {
     HgRepository *_repository;

File Source/HgTask.h

 #import <Cocoa/Cocoa.h>
 
 
+/** NSError domain for Mercurial related errors. */
 extern NSString* const HgErrorDomain;
+
+/** "hg" exit code, in the error's userInfo dict. */
 extern NSString* const HgErrorTaskExitCodeKey;
+ 
+/** The HgTask object itself, in the error's userInfo dict. */
 extern NSString* const HgErrorTaskObjectKey;
 enum {
     kHgGeneralError = 1,
     kHgTaskError = 2
 };
 
+/** Utility to create an NSError object, to be returned by methods that follow
+    the usual convention of setting an "out" NSError** parameter and returning NO.
+    This function stuffs the error into *outError and returns NO, so you can
+    directly return it. */
 BOOL HgMakeError( NSError **outError, NSString *format, ... );
 
 
+/** A generic souped-up NSTask, for running external command-line processes.
+    Makes it easy to mess with the argument list before starting,
+    and to capture the task output while it runs asynchronously. */
 @interface HgTask : NSObject 
 {
     @private

File Source/HgUncommittedRevision.h

 #import "HgRevision.h"
 
 
-/** Represents an uncommitted local modification of a file */
+/** Represents the uncommitted local modifications in a filesystem repository. */
 @interface HgUncommittedRevision : HgRevision
 
 - (id) initWithRepository: (HgRepository*)repository;

File Source/ImageAndTextCell.h

 #import <Cocoa/Cocoa.h>
 
+/** The venerable and indispensable Apple sample-code cell class.
+    Displays a Finder-like filename cell with attached icon. */
 @interface ImageAndTextCell : NSTextFieldCell {
 @private
     NSImage *image;

File Source/MercurialApp.h

 #import <Cocoa/Cocoa.h>
 
 
+/** The main application delegate class of Murky. */
 @interface MercurialApp : NSObject
 {
     IBOutlet NSPanel *_clonePanel;

File Source/Predicate.h

 #import <Cocoa/Cocoa.h>
 
 
+// This is a funky attempt to enable a cheesy, limited version of something like
+// blocks/closures.
+
 typedef BOOL (*PredicateFunction)( id objectToTest );
 typedef BOOL (*PredicateArgFunction)( id objectToTest, void *argument );
 

File Source/ProjectsController.h

 @class HgProject;
 
 
+/** Controller for the Projects window, which shows a user-configurable tree
+    of repositories and folders thereof, for quick access. */
 @interface ProjectsController : NSWindowController
 {
     IBOutlet NSOutlineView *_outline;

File Source/RepoController.h

 @class HgRepository, HgFile, HgRevision, HgTempDir, HgOperation;
 
 
+/** The controller for a repository window. */
 @interface RepoController : NSWindowController 
 {
     IBOutlet NSOutlineView *_outline;
 - (NSArray*) selectedFiles;
 @property (retain) HgRevision* selectedRevision;
 
-/* Returns the file that's actually selected in the file tree.
- This will be the same as -selectedFile, except while handling a right-click contextual menu
- (where -selectedFile returns the file right-clicked, but this returns the selected file.) */
+/** Returns the file that's actually selected in the file tree.
+    This will be the same as -selectedFile, except while handling a right-click contextual menu
+    (where -selectedFile returns the file right-clicked, but this returns the selected file.) */
 - (HgFile*) actuallySelectedFile;
 
 @property BOOL showsOnlyUncleanFiles;
 @end
 
 
+/** These are implemented in RepoController_Actions.m. */
 @interface RepoController (Actions)
 
 - (IBAction) refreshStatus: (id)sender;

File Source/RevisionGraphColumn.h

 @class HgRevision;
 
 
+/** Helper object for drawing the revision graph, one table-row at a time. */
 @interface RevisionGraphColumn : NSObject
 {
     NSArray *_revisions;
 @end
 
 
+/** An image cell for the repo controller's table view, which draws the current row's
+    segment of the revision graph. */
 @interface RevisionGraphCell : NSImageCell
 {
     RevisionGraphColumn *_graph;

File Source/URLFormatter.h

 #import <Cocoa/Cocoa.h>
 
 
+/** An NSFormatter for NSURL objects.
+    It formats a file: URL as a plain path, other URLs in absolute form, and nil as an empty string.
+    It intelligently parses user-entered URLs, turning absolute paths into file: URLs,
+    or adding a missing "http" prefix if necessary.
+    It also allows you to pop up a file picker, whose result will be entered as a path. */
 @interface URLFormatter : NSFormatter
 {
     NSArray *_allowedSchemes;