VLCKit.framework: Documentation updates, whitespace cleanup.

projects/macosx/framework/Headers/Internal/VLCEventManager.h

 /*****************************************************************************
- * VLCEventManager.h: VLC.framework VLCEventManager header
+ * VLCEventManager.h: VLCKit.framework VLCEventManager header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team

projects/macosx/framework/Headers/Internal/VLCLibVLCBridging.h

 /*****************************************************************************
-* VLCLibVLCbridging.h: VLC.framework VLCLibVLCBridging (Private) header
+* VLCLibVLCbridging.h: VLCKit.framework VLCLibVLCBridging (Private) header
 *****************************************************************************
 * Copyright (C) 2007 Pierre d'Herbemont
 * Copyright (C) 2007 the VideoLAN team
@@ -26,21 +26,18 @@
 #import "VLCMediaListAspect.h"
 #import "VLCStreamOutput.h"
 
+/* Utility functions */
 /**
- * Bridges functionality between libvlc and VLCMediaList implementation.
- */
-
-/*
- * Utility function
+ * \function catch_execption( ex )
+ * Utility function that catches a LibVLC generated exception by throwing a Cocoa based NSException.  
+ * \param ex LibVLC exception returned by LibVLC internal functions.
  */
-
 #define catch_exception( ex ) __catch_exception( (void *)(ex), __FUNCTION__, __FILE__, __LINE__ )
 extern void __catch_exception( void * e, const char * function, const char * file, int line_number );
 
-/*
- * @interface VLC(class) (LibVLCBridging)
+/**
+ * Bridges functionality between libvlc and VLCMediaList implementation.
  */
-
 @interface VLCMediaList (LibVLCBridging)
 /* Factories */
 /**
@@ -103,8 +100,6 @@ extern void __catch_exception( void * e, const char * function, const char * fil
  * \param value
  */
 - (void)setLength:(VLCTime *)value;
-
-
 @end
 
 /**
@@ -177,6 +172,9 @@ extern void __catch_exception( void * e, const char * function, const char * fil
 - (id)initWithLibrary:(VLCLibrary *)library;
 @end
 
+/**
+ * TODO: Documentation
+ */
 @interface VLCStreamOutput (LibVLCBridge)
 - (NSString *)representedLibVLCOptions;
 @end

projects/macosx/framework/Headers/Internal/VLCVideoCommon.h

 /*****************************************************************************
- * VLCVideoCommon.h: VLC.framework VLCVideoCommon header
+ * VLCVideoCommon.h: VLCKit.framework VLCVideoCommon header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -24,14 +24,19 @@
 
 #import <QuartzCore/QuartzCore.h>
 
+/**
+ * TODO: Documentation
+ */
 @interface VLCVideoLayoutManager : NSObject
 {
     CGSize originalVideoSize;
     BOOL  fillScreenEntirely;
 }
-@property BOOL  fillScreenEntirely;
-@property CGSize originalVideoSize;
 
+/* Factories */
 + (id)layoutManager;
 
+/* Properties */
+@property BOOL  fillScreenEntirely;
+@property CGSize originalVideoSize;
 @end

projects/macosx/framework/Headers/Public/VLCAudio.h

 /*****************************************************************************
- * VLCAudio.h: VLC.framework VLCAudio header
+ * VLCAudio.h: VLCKit.framework VLCAudio header
  *****************************************************************************
  * Copyright (C) 2007 Faustino E. Osuna
  * Copyright (C) 2007 the VideoLAN team

projects/macosx/framework/Headers/Public/VLCKit.h

 /*****************************************************************************
- * VLC.h: VLC.framework main header
+ * VLCKit.h: VLCKit.framework main header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -22,8 +22,9 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
-#ifndef VLC_FRAMEWORK_VLC_H
-#define VLC_FRAMEWORK_VLC_H
+/**
+ * TODO: Framework Documetnation
+ */
 
 #import <VLCKit/VLCLibrary.h>
 #import <VLCKit/VLCMedia.h>
@@ -43,5 +44,3 @@
 @class VLCMediaList;
 @class VLCTime;
 @class VLCVideoView;
\ No newline at end of file
-
-#endif /* VLC_FRAMEWORK_VLC_H */

projects/macosx/framework/Headers/Public/VLCLibrary.h

 /*****************************************************************************
- * VLCLibrary.h: VLC.framework VLCLibrary implementation
+ * VLCLibrary.h: VLCKit.framework VLCLibrary implementation
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -27,15 +27,20 @@
 #import "VLCMediaList.h"
 #import "VLCMedia.h"
 
-
+// FIXME: Hide from public header
 extern void * CreateSharedLibraryOnStartup( void ) __attribute__((constructor));
 extern void * DestroySharedLibraryAtExit( void ) __attribute__((destructor));
 
 @class VLCAudio;
 
 /**
- * VLCLibrary object.
- * TODO: Documentation VLCLibrary
+ * The VLCLibrary is the base library of the VLCKit.framework.  This object provides a shared instance that exposes the
+ * internal functionalities of libvlc and libvlc-control. The VLCLibrary object is instantiated automatically when
+ * VLCKit.framework is loaded into memory.  Also, it is automatically destroyed when the VLCKit.framework is unloaded
+ * from memory.
+ *
+ * Currently, the framework does not support multiple instances of VLCLibrary.  Furthermore, you cannot destroy any
+ * instiantiation of VLCLibrary, as previously noted, this is done automatically by the dynamic link loader.
  */
 @interface VLCLibrary : NSObject 
 {
@@ -45,13 +50,16 @@ extern void * DestroySharedLibraryAtExit( void ) __attribute__((destructor));
 
 /* Factories */
 /**
- * TODO: Documentation + [VLCLibrary sharedLibrary]
+ * Returns the library's shared instance.
+ * \return The library's shared instance.
  */
 + (VLCLibrary *)sharedLibrary;
 
 /* Properties */
 /**
- * TODO: Documentation VLCLibrary.audio
+ * Returns the library's audio object.  This object is used to manipulate the global audio properities of the shared
+ * library.
+ * \return The library's shared audio instance.
  */
 @property (readonly) VLCAudio * audio;
 @end

projects/macosx/framework/Headers/Public/VLCMedia.h

 /*****************************************************************************
- * VLCMedia.h: VLC.framework VLCMedia header
+ * VLCMedia.h: VLCKit.framework VLCMedia header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -100,29 +100,28 @@ typedef enum VLCMediaState
 
 /**
  * Defines files and streams as a managed object.  Each media object can be 
- * administered seperately.  VLCMediaPlayer or VLCMediaControl must be used 
+ * administered seperately.  VLCMediaPlayer or VLCMediaList must be used 
  * to execute the appropriate playback functions.
  * \see VLCMediaPlayer
- * \see VLCMediaControl
+ * \see VLCMediaList
  */
 @interface VLCMedia : NSObject
 {
     void *                p_md;              //< Internal media descriptor instance
-    NSURL *               url;               //< URL for this media resource
+    NSURL *               url;               //< URL (MRL) for this media resource
     VLCMediaList *        subitems;          //< Sub list of items
-    VLCTime *             length;            //< Duration of the media
+    VLCTime *             length;            //< Cached duration of the media
     NSMutableDictionary * metaDictionary;    //< Meta data storage
     id                    delegate;          //< Delegate object
     BOOL                  artFetched;        //< Value used to determine of the artwork has been preparsed
-    VLCMediaState         state;
+    VLCMediaState         state;             //< Current state of the media
 }
 
-/* Object Factories */
+/* Factories */
 /**
  * Manufactures a new VLCMedia object using the URL specified.
  * \param anURL URL to media to be accessed.
- * \return A new VLCMedia object, only if there were no errors.  This object 
- * will be automatically released.
+ * \return A new VLCMedia object, only if there were no errors.  This object will be automatically released.
  * \see initWithMediaURL
  */
 + (id)mediaWithURL:(NSURL *)anURL;
@@ -130,8 +129,7 @@ typedef enum VLCMediaState
 /**
  * Manufactures a new VLCMedia object using the path specified.
  * \param aPath Path to the media to be accessed.
- * \return A new VLCMedia object, only if there were no errors.  This object 
- * will be automatically released.
+ * \return A new VLCMedia object, only if there were no errors.  This object will be automatically released.
  * \see initWithPath
  */
 + (id)mediaWithPath:(NSString *)aPath;

projects/macosx/framework/Headers/Public/VLCMediaDiscoverer.h

 /*****************************************************************************
- * VLCMediaDiscoverer.h: VLC.framework VLCMediaDiscoverer header
+ * VLCMediaDiscoverer.h: VLCKit.framework VLCMediaDiscoverer header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team

projects/macosx/framework/Headers/Public/VLCMediaLibrary.h

 /*****************************************************************************
- * VLCMediaDiscoverer.h: VLC.framework VLCMediaDiscoverer header
+ * VLCMediaDiscoverer.h: VLCKit.framework VLCMediaDiscoverer header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -35,7 +35,7 @@
     void * mlib;
     VLCMediaList * allMedia;
 }
-/* Singleton */
+/* Factories */
 + (id)sharedMediaLibrary;
 
 /* Properties */

projects/macosx/framework/Headers/Public/VLCMediaList.h

 /*****************************************************************************
- * VLCMediaList.h: VLC.framework VLCMediaList header
+ * VLCMediaList.h: VLCKit.framework VLCMediaList header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team

projects/macosx/framework/Headers/Public/VLCMediaListAspect.h

 /*****************************************************************************
- * VLCMediaLisAspect.h: VLC.framework VLCMediaLisAspect header
+ * VLCMediaLisAspect.h: VLCKit.framework VLCMediaLisAspect header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team

projects/macosx/framework/Headers/Public/VLCMediaPlayer.h

 /*****************************************************************************
- * VLCMediaPlayer.h: VLC.framework VLCMediaPlayer header
+ * VLCMediaPlayer.h: VLCKit.framework VLCMediaPlayer header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -34,7 +34,7 @@ extern NSString * VLCMediaPlayerTimeChanged;
 extern NSString * VLCMediaPlayerStateChanged;
 
 /**
- * TODO: Documentation VLCMediaPlayerState
+ * VLCMediaPlayerState describes the state of the media player.
  */
 typedef enum VLCMediaPlayerState
 {
@@ -48,7 +48,9 @@ typedef enum VLCMediaPlayerState
 } VLCMediaPlayerState;
 
 /**
- * TODO: Documentation extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState)
+ * Returns the name of the player state as a string.
+ * \param state The player state.
+ * \return A string containing the name of state. If state is not a valid state, returns nil.
  */
 extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
 
@@ -58,12 +60,16 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
  */
 @protocol VLCMediaPlayerDelegate
 /**
- * TODO: Documentation - [VLCMediaPlayerDelegate ]
+ * Sent by the default notification center whenever the player's time has changed.
+ * \details Discussion The value of aNotification is always an VLCMediaPlayerTimeChanged notification. You can retrieve 
+ * the VLCMediaPlayer object in question by sending object to aNotification.
  */
 - (void)mediaPlayerTimeChanged:(NSNotification *)aNotification;
 
 /**
- * TODO: Documentation - [VLCMediaPlayerDelegate ]
+ * Sent by the default notification center whenever the player's state has changed.
+ * \details Discussion The value of aNotification is always an VLCMediaPlayerStateChanged notification. You can retrieve 
+ * the VLCMediaPlayer object in question by sending object to aNotification.
  */
 - (void)mediaPlayerStateChanged:(NSNotification *)aNotification;
 @end
@@ -72,12 +78,11 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
 @interface VLCMediaPlayer : NSObject 
 {
     id delegate;                        //< Object delegate
-
     void * instance;                    //  Internal
     VLCMedia * media;                   //< Current media being played
-    VLCTime * cachedTime;
-    VLCMediaPlayerState cachedState;
-    float position;
+    VLCTime * cachedTime;               //< Cached time of the media being played
+    VLCMediaPlayerState cachedState;    //< Cached state of the media being played
+    float position;                     //< The position of the media being played
 }
 
 /* Initializers */

projects/macosx/framework/Headers/Public/VLCTime.h

 /*****************************************************************************
- * VLCTime.h: VLC.framework VLCTime header
+ * VLCTime.h: VLCKit.framework VLCTime header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team

projects/macosx/framework/Headers/Public/VLCVideoLayer.h

 /*****************************************************************************
- * VLCVideoLayer.h: VLC.framework VLCVideoLayer header
+ * VLCVideoLayer.h: VLCKit.framework VLCVideoLayer header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -28,6 +28,8 @@
 {
     BOOL hasVideo;
 }
+
+/* Properties */
 @property (readonly) BOOL hasVideo;
 @property BOOL fillScreen;
 @end

projects/macosx/framework/Headers/Public/VLCVideoView.h

 /*****************************************************************************
- * VLCVideoView.h: VLC.framework VLCVideoView header
+ * VLCVideoView.h: VLCKit.framework VLCVideoView header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
  * Copyright (C) 2007 the VideoLAN team
@@ -34,6 +34,7 @@
     BOOL hasVideo;
 }
 
+/* Properties */
 @property (assign) id delegate;
 @property (copy) NSColor *backColor;
 @property BOOL fillScreen;