Dialog: add missing API documentation

Headers/Public/VLCDialogProvider.h

@@ -31,13 +31,39 @@ typedef NS_ENUM(NSUInteger, VLCDialogQuestionType) {
 
 @protocol VLCCustomDialogRendererProtocol <NSObject>
 
+/**
+ * called when VLC wants to show an error
+ * \param the dialog title
+ * \param the error message
+ */
 - (void)showErrorWithTitle:(NSString * _Nonnull)error
       message:(NSString * _Nonnull)message;
+
+/**
+ * called when user logs in to something
+ * If VLC includes a keychain module for your platform, a user can store stuff
+ * \param login title
+ * \param an explaining message
+ * \param a default username within context
+ * \param indicator whether storing is even a possibility
+ * \param reference you need to send the results to
+ */
 - (void)showLoginWithTitle:(NSString * _Nonnull)title
                    message:(NSString * _Nonnull)message
            defaultUsername:(NSString * _Nullable)username
           askingForStorage:(BOOL)askingForStorage
              withReference:(NSValue * _Nonnull)reference;
+
+/**
+ * called when VLC needs the user to decide something
+ * \param the dialog title
+ * \param an explaining message text
+ * \param a question type
+ * \param cancel button text
+ * \param action 1 text
+ * \param action 2 text
+ * \param reference you need to send the action to
+ */
 - (void)showQuestionWithTitle:(NSString * _Nonnull)title
                       message:(NSString * _Nonnull)message
                          type:(VLCDialogQuestionType)questionType
@@ -45,15 +71,35 @@ typedef NS_ENUM(NSUInteger, VLCDialogQuestionType) {
                 action1String:(NSString * _Nullable)action1String
                 action2String:(NSString * _Nullable)action2String
                 withReference:(NSValue * _Nonnull)reference;
+
+/**
+ * called when VLC wants to show some progress
+ * \param the dialog title
+ * \param an explaining message
+ * \param indicator whether progress indeterminate
+ * \param initial progress position
+ * \param optional string for cancel button if operation is cancellable
+ * \param reference VLC will include in updates
+ */
 - (void)showProgressWithTitle:(NSString * _Nonnull)title
                       message:(NSString * _Nonnull)message
               isIndeterminate:(BOOL)isIndeterminate
                      position:(float)position
                  cancelString:(NSString * _Nullable)cancelString
                 withReference:(NSValue * _Nonnull)reference;
+
+/** called when VLC wants to update an existing progress dialog
+ * \param reference to the existing progress dialog
+ * \param updated message
+ * \param current position
+ */
 - (void)updateProgressWithReference:(NSValue * _Nonnull)reference
                             message:(NSString * _Nullable)message
                             postion:(float)position;
+
+/** VLC decided to destroy a dialog
+ * \param reference to the dialog to destroy
+ */
 - (void)cancelDialogWithReference:(NSValue * _Nonnull)reference;
 
 @end
@@ -68,7 +114,8 @@ typedef NS_ENUM(NSUInteger, VLCDialogQuestionType) {
  * \note if library param is NULL, [VLCLibrary sharedLibrary] will be used
  * \return the dialog provider instance, can be NULL on malloc failures
  */
-- (instancetype __nullable)initWithLibrary:(VLCLibrary * __nullable)library customUI:(BOOL)customUI;
+- (instancetype __nullable)initWithLibrary:(VLCLibrary * __nullable)library
+                                  customUI:(BOOL)customUI;
 
 /**
  * initializer method to run the dialog provider instance on a specific library instance
@@ -78,8 +125,30 @@ typedef NS_ENUM(NSUInteger, VLCDialogQuestionType) {
  */
 @property (weak, readwrite, nonatomic, nullable) id<VLCCustomDialogRendererProtocol> customRenderer;
 
-- (void)postUsername:(NSString * _Nullable)username andPassword:(NSString * _Nullable)password forDialogReference:(NSValue * _Nonnull)dialogReference store:(BOOL)store;
-- (void)postAction:(int)buttonNumber forDialogReference:(NSValue * _Nonnull)dialogReference;
+/**
+ * if you requested custom UI mode for dialogs, use this method respond to a login dialog
+ * \param username or NULL if cancelled
+ * \param password or NULL if cancelled
+ * \param reference to the dialog you respond to
+ * \param shall VLC store the login securely?
+ * \note This method does not have any effect if you don't use custom UI mode */
+- (void)postUsername:(NSString * _Nullable)username
+         andPassword:(NSString * _Nullable)password
+  forDialogReference:(NSValue * _Nonnull)dialogReference
+               store:(BOOL)store;
+
+/**
+ * if you requested custom UI mode for dialogs, use this method respond to a question dialog
+ * \param the button number the user pressed, use 3 if s/he cancelled, otherwise respectively 1 or 2 depending on the selected action
+ * \param reference to the dialog you respond to
+ * \note This method does not have any effect if you don't use custom UI mode */
+- (void)postAction:(int)buttonNumber
+forDialogReference:(NSValue * _Nonnull)dialogReference;
+
+/**
+ * if you requested custom UI mode for dialogs, use this method to cancel a progress dialog
+ * \param reference to the dialog you want to cancel
+ * \note This method does not have any effect if you don't use custom UI mode */
 - (void)dismissDialogWithReference:(NSValue * _Nonnull)dialogReference;
 
 @end