media list: add doxygen documentation

Headers/Public/VLCMediaList.h

@@ -2,7 +2,8 @@
  * VLCMediaList.h: VLCKit.framework VLCMediaList header
  *****************************************************************************
  * Copyright (C) 2007 Pierre d'Herbemont
- * Copyright (C) 2007 VLC authors and VideoLAN
+ * Copyright (C) 2015 Felix Paul Kühne
+ * Copyright (C) 2007, 2015 VLC authors and VideoLAN
  * $Id$
  *
  * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
@@ -33,23 +34,30 @@ extern NSString *const VLCMediaListItemDeleted;
 @class VLCMediaList;
 
 /**
- * TODO: Documentation VLCMediaListDelegate
+ * VLCMediaListDelegate
  */
 @protocol VLCMediaListDelegate
 @optional
 /**
- * TODO: Documentation - [VLCMediaListDelegate mediaList:mediaAdded:atIndex:]
+ * delegate method triggered when a media was added to the list
+ *
+ * \param the media list
+ * \param the media object that was added
+ * \param the index the media object was added at
  */
 - (void)mediaList:(VLCMediaList *)aMediaList mediaAdded:(VLCMedia *)media atIndex:(NSInteger)index;
 
 /**
- * TODO: Documentation - [VLCMediaListDelegate mediaList:mediaRemovedAtIndex:]
+ * delegate method triggered when a media was removed from the list
+ *
+ * \param the media list
+ * \param the index a media item was deleted at
  */
 - (void)mediaList:(VLCMediaList *)aMediaList mediaRemovedAtIndex:(NSInteger)index;
 @end
 
 /**
- * TODO: Documentation VLCMediaList
+ * VLCMediaList
  */
 @interface VLCMediaList : NSObject
 
@@ -57,53 +65,72 @@ extern NSString *const VLCMediaListItemDeleted;
 
 /* Operations */
 /**
- * TODO: Documentation - [VLCMediaList lock]
+ * lock the media list from being edited by another thread
  */
 - (void)lock;
 
 /**
- * TODO: Documentation - [VLCMediaList unlock]
+ * unlock the media list from being edited by another thread
  */
 - (void)unlock;
 
 /**
- * TODO: Documentation - [VLCMediaList addMedia:]
+ * add a media to a read-write list
+ *
+ * \param the media object to add
+ * \return the index of the newly added media
+ * \note this function silently fails if the list is read-only
  */
 - (NSInteger)addMedia:(VLCMedia *)media;
 
 /**
- * TODO: Documentation - [VLCMediaList insertMedia:atIndex:]
+ * add a media to a read-write list at a given position
+ *
+ * \param the media object to add
+ * \param the index where to add the given media
+ * \note this function silently fails if the list is read-only
  */
 - (void)insertMedia:(VLCMedia *)media atIndex:(NSInteger)index;
 
 /**
- * TODO: Documentation - [VLCMediaList removeMediaAtIndex:]
+ * remove a media from a given position
+ *
+ * \param the index of the media to remove
+ * \note this function silently fails if the list is read-only
  */
 - (void)removeMediaAtIndex:(NSInteger)index;
 
 /**
- * TODO: Documentation - [VLCMediaList mediaAtIndex:]
+ * retrieve a media from a given position
+ *
+ * \param the index of the media you want
+ * \return the media object
  */
 - (VLCMedia *)mediaAtIndex:(NSInteger)index;
 
 /**
- * TODO: Documentation - [VLCMediaList indexOfMedia:]
+ * retrieve the position of a media item
+ *
+ * \param the media object to search for
+ * \return the index position of the media in the list or -1 if not found
  */
 - (NSInteger)indexOfMedia:(VLCMedia *)media;
 
 /* Properties */
 /**
- * TODO: Documentation VLCMediaList.count
+ * number of media items in the list
+ * \return the number of media objects
  */
 @property (readonly) NSInteger count;
 
 /**
- * TODO: Documentation VLCMediaList.delegate
+ * delegate property to listen to addition/removal events
  */
 @property (weak) id delegate;
 
 /**
- * TODO: Documentation VLCMediaList.isReadOnly
+ * read-only property to check if the media list is writable or not
+ * \return boolean value if the list is read-only
  */
 @property (readonly) BOOL isReadOnly;