Add complete documentation

Headers/Public/VLCExtension.h

@@ -28,10 +28,25 @@
  */
 @interface VLCExtension : NSObject
 
+/**
+ * initializer for wrapper class
+ * \param instance the extension_t instance to init the wrapper with
+ */
 - (instancetype)initWithInstance:(struct extension_t *)instance NS_DESIGNATED_INITIALIZER; // FIXME: Should be internal
+
+/**
+ * the extension instance used to init the wrapper with
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly) struct extension_t *instance; // FIXME: Should be internal
 
+/**
+ * technical name of the extension
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly, copy) NSString *name;
+
+/**
+ * user-visible name of the extension
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly, copy) NSString *title;
 
 @end

Headers/Public/VLCExtensionsManager.h

@@ -30,10 +30,25 @@
  */
 @interface VLCExtensionsManager : NSObject
 
+/**
+ * singleton manager instance
+ */
 + (VLCExtensionsManager *)sharedManager;
+
+/**
+ * list of available extensions
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *extensions;
+
+/**
+ * start execution of a given extension instance
+ * \param extension the extension to run
+ */
 - (void)runExtension:(VLCExtension *)extension;
 
+/**
+ * player instance to use with the extensions
+ */
 @property (readwrite, strong) VLCMediaPlayer *mediaPlayer;
 
 @end

Headers/Public/VLCLibrary.h

@@ -107,6 +107,10 @@
  */
 - (void)setApplicationIdentifier:(NSString *)identifier withVersion:(NSString *)version andApplicationIconName:(NSString *)icon;
 
+/**
+ * the libvlc instance wrapped by the VLCLibrary instance
+ * \note if you want to use it, you are most likely wrong (or want to add a proper ObjC API)
+ */
 @property (nonatomic, assign) void *instance;
 
 @end

Headers/Public/VLCMedia.h

@@ -81,22 +81,6 @@ typedef NS_ENUM(NSInteger, VLCMediaState) {
  * trapped.
  */
 @protocol VLCMediaDelegate <NSObject>
-// TODO: SubItemAdded/SubItemRemoved implementation.  Not sure if we really want to implement this.
-///**
-// * Delegate method called whenever a sub item has been added to the specified VLCMedia.
-// * \param aMedia The media resource that has received the new sub item.
-// * \param childMedia The new sub item added.
-// * \param index Location of the new subitem in the aMedia's sublist.
-// */
-// - (void)media:(VLCMedia *)media addedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
-
-///**
-// * Delegate method called whenever a sub item has been removed from the specified VLCMedia.
-// * \param aMedia The media resource that has had a sub item removed from.
-// * \param childMedia The sub item removed.
-// * \param index The previous location of the recently removed sub item.
-// */
-// - (void)media:(VLCMedia *)aMedia removedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
 
 @optional
 
@@ -180,6 +164,9 @@ typedef NS_ENUM(NSInteger, VLCMediaState) {
  */
 - (instancetype)initAsNodeWithName:(NSString *)aName;
 
+/**
+ * list of possible media types that could be returned by "mediaType"
+ */
 typedef NS_ENUM(NSUInteger, VLCMediaType) {
     VLCMediaTypeUnknown,
     VLCMediaTypeFile,
@@ -235,6 +222,9 @@ typedef NS_ENUM(NSUInteger, VLCMediaType) {
  */
 @property (nonatomic, readonly) BOOL isParsed __attribute__((deprecated));
 
+/**
+ * list of possible parsed states returnable by parsedStatus
+ */
 typedef NS_ENUM(unsigned, VLCMediaParsedStatus)
 {
     VLCMediaParsedStatusInit = 0,
@@ -397,12 +387,20 @@ extern NSString *const VLCMediaTracksInformationFrameRateDenominator;
 extern NSString *const VLCMediaTracksInformationTextEncoding;
 
 /**
- * Tracks information NSDictionary values for
- * VLCMediaTracksInformationType
+ * audio track information NSDictionary value for VLCMediaTracksInformationType
  */
 extern NSString *const VLCMediaTracksInformationTypeAudio;
+/**
+ * video track information NSDictionary value for VLCMediaTracksInformationType
+ */
 extern NSString *const VLCMediaTracksInformationTypeVideo;
+/**
+ * text / subtitles track information NSDictionary value for VLCMediaTracksInformationType
+ */
 extern NSString *const VLCMediaTracksInformationTypeText;
+/**
+ * unknown track information NSDictionary value for VLCMediaTracksInformationType
+ */
 extern NSString *const VLCMediaTracksInformationTypeUnknown;
 
 /**
@@ -466,6 +464,10 @@ enum {
     VLCMediaFetchLocal          = 0x02,
     VLCMediaFetchNetwork        = 0x04,
 };
+/**
+ * enum of available options for use with parseWithOptions
+ * \note you may pipe multiple values for the single parameter
+ */
 typedef int VLCMediaParsingOptions;
 
 /**

Headers/Public/VLCMediaDiscoverer.h

@@ -51,6 +51,10 @@ extern NSString *const VLCMediaDiscovererCategory;
 
 @interface VLCMediaDiscoverer : NSObject
 
+/**
+ * The library instance used by the discoverers
+ * \note unless for debug, you are wrong if you want to use this selector
+ */
 @property (nonatomic, readonly) VLCLibrary *libraryInstance;
 
 /**

Headers/Public/VLCMediaLibrary.h

@@ -27,14 +27,18 @@
 @class VLCMediaList;
 
 /**
- * TODO: Documentation
+ * media library stub
  */
 @interface VLCMediaLibrary : NSObject
 
-/* Factories */
+/**
+* library singleton
+*/
 + (VLCMediaLibrary*)sharedMediaLibrary;
 
-/* Properties */
+/**
+ * list of all media
+ */
 @property (nonatomic, readonly, strong) VLCMediaList * allMedia;
 
 @end

Headers/Public/VLCMediaList.h

@@ -26,8 +26,13 @@
 #import <Foundation/Foundation.h>
 #import "VLCMedia.h"
 
-/* Notification Messages */
+/**
+ * notification name if a list item was added
+ */
 extern NSString *const VLCMediaListItemAdded;
+/**
+ * notification name if a list item was deleted
+ */
 extern NSString *const VLCMediaListItemDeleted;
 
 @class VLCMedia;
@@ -61,6 +66,12 @@ extern NSString *const VLCMediaListItemDeleted;
  */
 @interface VLCMediaList : NSObject
 
+/**
+ * initializer with a set of VLCMedia instances
+ * \param array the NSArray of VLCMedia instances
+ * \return instance of VLCMediaList equipped with the VLCMedia instances
+ * \see VLCMedia
+ */
 - (instancetype)initWithArray:(NSArray *)array;
 
 /* Operations */

Headers/Public/VLCMediaListPlayer.h

@@ -37,10 +37,14 @@ typedef NS_ENUM(NSInteger, VLCRepeatMode) {
 };
 
 /**
- * A media list player, which eases the use of playlists */ 
+ * A media list player, which eases the use of playlists
  */
 @interface VLCMediaListPlayer : NSObject
 
+/**
+ * setter/getter for mediaList to play within the player
+ * \note This list is erased when setting a rootMedia on the list player instance
+ */
 @property (readwrite) VLCMediaList *mediaList;
 
 /**
@@ -49,24 +53,51 @@ typedef NS_ENUM(NSInteger, VLCRepeatMode) {
  * Setting mediaList will erase rootMedia.
  */
 @property (readwrite) VLCMedia *rootMedia;
+
+/**
+ * the media player instance used for playback by the list player
+ */
 @property (readonly) VLCMediaPlayer *mediaPlayer;
 
+/**
+ * initializer with a certain drawable
+ * \note drawable can also be set later
+ */
 - (instancetype)initWithDrawable:(id)drawable;
+/**
+ * initializer with a custom options
+ * \note This is will initialize a new VLCLibrary instance, which WILL have a major memory impact
+ */
 - (instancetype)initWithOptions:(NSArray *)options;
+/**
+ * initializer with a certain drawable and options
+ * \see initWithDrawable
+ * \see initWithOptions
+ */
 - (instancetype)initWithOptions:(NSArray *)options andDrawable:(id)drawable;
 
 /**
- * Basic play, pause and stop are here. For other methods, use the mediaPlayer.
+ * start playback
  */
 - (void)play;
+/**
+ * pause playback
+ */
 - (void)pause;
+/**
+ * stop playback
+ */
 - (void)stop;
 
 /**
- * previous, next, play item at index
+ * play next item
  * \returns YES on success, NO if there is no such item
  */
 @property (NS_NONATOMIC_IOSONLY, readonly) BOOL next;
+/**
+ * play previous item
+ * \returns YES on success, NO if there is no such item
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly) BOOL previous;
 
 /**
@@ -84,7 +115,6 @@ typedef NS_ENUM(NSInteger, VLCRepeatMode) {
  * Playmode selection (don't repeat anything, repeat one, repeat all)
  * See VLCRepeatMode.
  */
-
 @property (readwrite) VLCRepeatMode repeatMode;
 
 /**

Headers/Public/VLCMediaPlayer.h

@@ -132,15 +132,42 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
  */
 @interface VLCMediaPlayer : NSObject
 
+/**
+ * the library instance in use by the player instance
+ */
 @property (nonatomic, readonly) VLCLibrary *libraryInstance;
+/**
+ * the delegate object implementing the optional protocol
+ */
 @property (weak, nonatomic) id<VLCMediaPlayerDelegate> delegate;
 
 #if !TARGET_OS_IPHONE
 /* Initializers */
+/**
+ * initialize player with a given video view
+ * \param aVideoView an instance of VLCVideoView
+ * \note This initializer is for macOS only
+ */
 - (instancetype)initWithVideoView:(VLCVideoView *)aVideoView;
+/**
+ * initialize player with a given video layer
+ * \param aVideoLayer an instance of VLCVideoLayer
+ * \note This initializer is for macOS only
+ */
 - (instancetype)initWithVideoLayer:(VLCVideoLayer *)aVideoLayer;
 #endif
+/**
+ * initialize player with a given set of options
+ * \param options an array of private options
+ * \note This will allocate a new libvlc and VLCLibrary instance, which will have a memory impact
+ */
 - (instancetype)initWithOptions:(NSArray *)options;
+/**
+ * initialize player with a certain libvlc instance and VLCLibrary
+ * \param playerInstance the libvlc instance
+ * \param library the library instance
+ * \note This is an advanced initializer for very specialized environments
+ */
 - (instancetype)initWithLibVLCInstance:(void *)playerInstance andLibrary:(VLCLibrary *)library;
 
 /* Video View Options */
@@ -150,10 +177,24 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
 #pragma mark video functionality
 
 #if !TARGET_OS_IPHONE
+/**
+ * set a video view for rendering
+ * \param aVideoView instance of VLCVideoView
+ * \note This setter is macOS only
+ */
 - (void)setVideoView:(VLCVideoView *)aVideoView;
+/**
+ * set a video layer for rendering
+ * \param aVideoLayer instance of VLCVideoLayer
+ * \note This setter is macOS only
+ */
 - (void)setVideoLayer:(VLCVideoLayer *)aVideoLayer;
 #endif
 
+/**
+ * set/retrieve a video view for rendering
+ * This can be any UIView or NSView or instances of VLCVideoView / VLCVideoLayer if running on macOS
+ */
 @property (strong) id drawable; /* The videoView or videoLayer */
 
 /**
@@ -251,6 +292,10 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
  */
 @property (nonatomic) float rate;
 
+/**
+ * an audio controller object
+ * \return instance of VLCAudio
+ */
 @property (nonatomic, readonly, weak) VLCAudio * audio;
 
 /* Video Information */
@@ -285,10 +330,15 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
 
 /**
  * Returns the current position (or time) of the feed.
- * \return VLCTIme object with current time.
+ * \return VLCTime object with current time.
  */
 @property (NS_NONATOMIC_IOSONLY, strong) VLCTime *time;
 
+/**
+ * Returns the current position (or time) of the feed, inversed if a duration is available
+ * \return VLCTime object with requested time
+ * \note VLCTime will be a nullTime if no duration can be calculated for the current input
+ */
 @property (nonatomic, readonly, weak) VLCTime *remainingTime;
 
 #pragma mark -
@@ -390,14 +440,22 @@ typedef NS_ENUM(unsigned, VLCMediaPlaybackSlaveType)
  */
 
 /**
- * Return the current video subtitle index, or
+ * Return the current chapter index, or
  * \return NSNotFound if none is set.
- *
- * To disable subtitle pass NSNotFound.
  */
 @property (readwrite) int currentChapterIndex;
+/**
+ * switch to the previous chapter
+ */
 - (void)previousChapter;
+/**
+ * switch to the next chapter
+ */
 - (void)nextChapter;
+/**
+ * returns the number of chapters for a given title
+ * \param titleIndex the index of the title you are requesting the chapters for
+ */
 - (int)numberOfChaptersForTitle:(int)titleIndex;
 
 /**
@@ -406,8 +464,17 @@ typedef NS_ENUM(unsigned, VLCMediaPlaybackSlaveType)
  */
 - (NSArray *)chaptersForTitleIndex:(int)titleIndex __attribute__((deprecated));
 
+/**
+ * dictionary value for the user-facing chapter name
+ */
 extern NSString *const VLCChapterDescriptionName;
+/**
+ * dictionary value for the chapter's time offset
+ */
 extern NSString *const VLCChapterDescriptionTimeOffset;
+/**
+ * dictionary value for the chapter's duration
+ */
 extern NSString *const VLCChapterDescriptionDuration;
 
 /**
@@ -416,6 +483,9 @@ extern NSString *const VLCChapterDescriptionDuration;
  * chapter name, time offset and duration
  * \note if no title value is provided, information about the chapters of the current title is returned
  * \return array describing the titles in details
+ * \see VLCChapterDescriptionName
+ * \see VLCChapterDescriptionTimeOffset
+ * \see VLCChapterDescriptionDuration
  */
 - (NSArray *)chapterDescriptionsOfTitle:(int)titleIndex;
 
@@ -424,6 +494,10 @@ extern NSString *const VLCChapterDescriptionDuration;
  * \return NSNotFound if none is set.
  */
 @property (readwrite) int currentTitleIndex;
+/**
+ * number of titles available for the current media
+ * \return the number of titles
+ */
 @property (readonly) int numberOfTitles;
 
 /**
@@ -437,8 +511,17 @@ extern NSString *const VLCChapterDescriptionDuration;
  */
 @property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *titles __attribute__((deprecated));
 
+/**
+ * dictionary value for the user-facing title name
+ */
 extern NSString *const VLCTitleDescriptionName;
+/**
+ * dictionary value for the title's duration
+ */
 extern NSString *const VLCTitleDescriptionDuration;
+/**
+ * dictionary value whether the title is a menu or not
+ */
 extern NSString *const VLCTitleDescriptionIsMenu;
 
 /**
@@ -446,6 +529,9 @@ extern NSString *const VLCTitleDescriptionIsMenu;
  * an array of all titles of the current media including information
  * of name, duration and potential menu state
  * \return array describing the titles in details
+ * \see VLCTitleDescriptionName
+ * \see VLCTitleDescriptionDuration
+ * \see VLCTitleDescriptionIsMenu
  */
 @property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *titleDescriptions;
 
@@ -487,6 +573,10 @@ extern NSString *const VLCTitleDescriptionIsMenu;
 #pragma mark -
 #pragma mark audio functionality
 
+/**
+ * sets / returns the current audio channel
+ * \return the currently set audio channel
+ */
 @property (NS_NONATOMIC_IOSONLY) int audioChannel;
 
 /**
@@ -502,7 +592,7 @@ extern NSString *const VLCTitleDescriptionIsMenu;
 
 /**
  * Get a list of available equalizer profiles
- * \Note Current versions do not allow the addition of further profiles
+ * \note Current versions do not allow the addition of further profiles
  *       so you need to handle this in your app.
  *
  * \return array of equalizer profiles
@@ -511,7 +601,7 @@ extern NSString *const VLCTitleDescriptionIsMenu;
 
 /**
  * Re-set the equalizer to a profile retrieved from the list
- * \Note This doesn't enable the Equalizer automagically
+ * \note This doesn't enable the Equalizer automagically
  */
 - (void)resetEqualizerFromProfile:(unsigned)profile;
 
@@ -555,6 +645,9 @@ extern NSString *const VLCTitleDescriptionIsMenu;
 #pragma mark media handling
 
 /* Media Options */
+/**
+ * The currently media instance set to play
+ */
 @property (NS_NONATOMIC_IOSONLY, strong) VLCMedia *media;
 
 #pragma mark -
@@ -692,15 +785,25 @@ extern NSString *const VLCTitleDescriptionIsMenu;
  */
 @property (NS_NONATOMIC_IOSONLY, getter=isSeekable, readonly) BOOL seekable;
 
+/**
+ * property whether the currently playing media can be paused (or not)
+ * \return BOOL value
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly) BOOL canPause;
 
 #if TARGET_OS_IPHONE
+/**
+ * Array of taken snapshots of the current video output
+ * \return a NSArray of UIImage instances
+ * \note This property is not available to macOS
+ */
 @property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *snapshots;
 
 /**
  * Get last snapshot available.
  * \return an UIImage with the last snapshot available.
  * \note return value is nil if there is no snapshot
+ * \note This property is not available to macOS
  */
 @property (NS_NONATOMIC_IOSONLY, readonly) UIImage *lastSnapshot;
 #endif

Headers/Public/VLCMediaThumbnailer.h

@@ -34,13 +34,44 @@
  */
 @interface VLCMediaThumbnailer : NSObject
 
+/**
+ * initializer
+ * \param media the media item to thumbnail
+ * \param delegate the delegate implementing the required protocol
+ * \return the thumbnailer instance
+ * \note This will use the default shared library instance
+ */
 + (VLCMediaThumbnailer *)thumbnailerWithMedia:(VLCMedia *)media andDelegate:(id<VLCMediaThumbnailerDelegate>)delegate;
+/**
+ * initializer
+ * \param media the media item to thumbnail
+ * \param delegate the delegate implementing the required protocol
+ * \param library a library instance, potentially configured by you in a special way
+ * \return the thumbnailer instance
+ */
 + (VLCMediaThumbnailer *)thumbnailerWithMedia:(VLCMedia *)media delegate:(id<VLCMediaThumbnailerDelegate>)delegate andVLCLibrary:(VLCLibrary *)library;
+
+/**
+ * Starts the thumbnailing process
+ */
 - (void)fetchThumbnail;
 
+/**
+ * delegate object associated with the thumbnailer instance implementing the required protocol
+ */
 @property (readwrite, weak, nonatomic) id<VLCMediaThumbnailerDelegate> delegate;
+/**
+ * the media object that is being thumbnailed
+ */
 @property (readwrite, nonatomic) VLCMedia *media;
+/**
+ * The thumbnail created for the media object
+ */
 @property (readwrite, assign, nonatomic) CGImageRef thumbnail;
+/**
+ * the libvlc instance used for thumbnailing
+ * \note Whatever you do, using this instance is most likely wrong
+ */
 @property (readwrite) void * libVLCinstance;
 
 /**
@@ -73,6 +104,16 @@
  */
 @protocol VLCMediaThumbnailerDelegate
 @required
+/**
+ * called when the thumbnailing process timed-out
+ * \param mediaThumbnailer the thumbnailer instance that timed out
+ * \note The time-out duration depends on various factors outside your control and will not be the same for different media
+ */
 - (void)mediaThumbnailerDidTimeOut:(VLCMediaThumbnailer *)mediaThumbnailer;
+/**
+ * called when the thumbnailer did successfully created a thumbnail
+ * \param mediaThumbnailer the thumbnailer instance that was successful
+ * \param thumbnail the thumbnail that was created
+ */
 - (void)mediaThumbnailer:(VLCMediaThumbnailer *)mediaThumbnailer didFinishThumbnail:(CGImageRef)thumbnail;
 @end

Headers/Public/VLCTime.h

@@ -29,26 +29,88 @@
  */
 @interface VLCTime : NSObject
 
-/* Factories */
+/**
+ * factorize an empty time object
+ * \return the VLCTime object
+ */
 + (VLCTime *)nullTime;
+/**
+ * factorize a time object with a given number object
+ * \param aNumber the NSNumber object with a time in milliseconds
+ * \return the VLCTime object
+ */
 + (VLCTime *)timeWithNumber:(NSNumber *)aNumber;
+/**
+ * factorize a time object with a given integer
+ * \param aInt the int with a time in milliseconds
+ * \return the VLCTime object
+ */
 + (VLCTime *)timeWithInt:(int)aInt;
 
-/* Initializers */
+/**
+ * init a time object with a given number object
+ * \param aNumber the NSNumber object with a time in milliseconds
+ * \return the VLCTime object
+ */
 - (instancetype)initWithNumber:(NSNumber *)aNumber;
+/**
+ * init a time object with a given integer
+ * \param aInt the int with a time in milliseconds
+ * \return the VLCTime object
+ */
 - (instancetype)initWithInt:(int)aInt;
 
 /* Properties */
+/**
+ * the current time value as NSNumber
+ * \return the NSNumber object
+ */
 @property (nonatomic, readonly) NSNumber * value;	///< Holds, in milliseconds, the VLCTime value
-@property (readonly) NSNumber * numberValue;		// here for backwards compatibility
+/**
+ * the current time value as NSNumber
+ * \return the NSNumber object
+ * \deprecated use value instead
+ */
+@property (readonly) NSNumber * numberValue __attribute__((deprecated));		// here for backwards compatibility
+
+/**
+ * the current time value as string value localized for the current environment
+ * \return the NSString object
+ */
 @property (readonly) NSString * stringValue;
+/**
+ * the current time value as verbose string value localized for the current environment
+ * \return the NSString object
+ */
 @property (readonly) NSString * verboseStringValue;
+/**
+ * the current time value as string value localized for the current environment representing the time in minutes
+ * \return the NSString object
+ */
 @property (readonly) NSString * minuteStringValue;
+/**
+ * the current time value as int value
+ * \return the int
+ */
 @property (readonly) int intValue;
 
 /* Comparators */
+/**
+ * compare the current VLCTime instance against another instance
+ * \param aTime the VLCTime instance to compare against
+ * \return a NSComparisonResult
+ */
 - (NSComparisonResult)compare:(VLCTime *)aTime;
+/**
+ * compare the current VLCTime instance against another instance
+ * \param object the VLCTime instance to compare against
+ * \return a BOOL whether the instances are equal or not
+ */
 - (BOOL)isEqual:(id)object;
+/**
+ * Calculcate a unique hash for the current time instance
+ * \return a hash value
+ */
 - (NSUInteger)hash;
 
 @end

Headers/Public/VLCVideoLayer.h

@@ -29,7 +29,15 @@
  */
 @interface VLCVideoLayer : CALayer
 
+/**
+ * Is a video being rendered in this layer?
+ * \return the BOOL value
+ */
 @property (nonatomic, readonly) BOOL hasVideo;
+/**
+ * Should the video fill the screen by adding letterboxing or stretching?
+ * \return the BOOL value
+ */
 @property (nonatomic) BOOL fillScreen;
 
 @end

Headers/Public/VLCVideoView.h

@@ -31,9 +31,20 @@
 @interface VLCVideoView : NSView
 
 /* Properties */
-@property (nonatomic, weak) id delegate;
+/**
+* NSColor to set as the view background if no video is being rendered
+*/
 @property (nonatomic, copy) NSColor *backColor;
 
-@property BOOL fillScreen;
+/**
+ * Is a video being rendered in this layer?
+ * \return the BOOL value
+ */
 @property (nonatomic, readonly) BOOL hasVideo;
+/**
+ * Should the video fill the screen by adding letterboxing or stretching?
+ * \return the BOOL value
+ */
+@property (nonatomic) BOOL fillScreen;
+
 @end