From: moon87.park <moon87.park@samsung.com>
Date: Tue, 16 May 2017 07:39:30 +0000 (+0900)
Subject: [Attach-panel] Add comment
X-Git-Tag: accepted/tizen/unified/20170630.083217^2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=56a6ea4bd2960f83d15f97aa65b55966484e5cd7;p=platform%2Fcore%2Fcsapi%2Fattach-panel.git

[Attach-panel] Add comment

Change-Id: I89e4e130b69f13052d1ed27a72c22a08770935d8
---

diff --git a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanel.cs b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanel.cs
index 899c913..f6edb4c 100755
--- a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanel.cs
+++ b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanel.cs
@@ -2,20 +2,26 @@ using System;
 
 namespace Tizen.Applications.AttachPanel
 {
+    /// <summary>
+    /// Represents immutable class for attach panel.
+    /// </summary>
     public partial class AttachPanel
     {
-        private const string LogTag = "Tizen.Applications.AttachPanel";
-
-        private static IntPtr _attachPanel;
-
-        private static event EventHandler<StateEventArgs> _eventEventHandler;
-        private static event EventHandler<ResultEventArgs> _resultEventHandler;
-
-        private static Interop.AttachPanel.AttachPanelEventCallback SetEventListener;
-        private static Interop.AttachPanel.AttachPanelResultCallback SetResultListener;
-
+        //private const string LogTag = "Tizen.Applications.AttachPanel";
+
+        /// <summary>
+        /// Represents immutable class for attach panel. 
+        /// </summary>
+        /// <since_tizen> 3 </since_tizen>
+        /// <param name="conformant">The caller's conformant</param>
+        /// <exception cref="OutOfMemoryException">Thrown when an attempt to allocate memory fails.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is already exist or the <paramref name="conformant"/> is not a conformant object</exception>
         public AttachPanel(IntPtr conformant)
         {
+            if (conformant == IntPtr.Zero)
+            {
+                throw new ArgumentNullException("Use the value property, not null value");
+            }
             _attachPanel = new IntPtr();
             Interop.AttachPanel.ErrorCode err = Interop.AttachPanel.CreateAttachPanel(conformant, ref _attachPanel);
             checkException(err);
@@ -41,6 +47,10 @@ namespace Tizen.Applications.AttachPanel
             }
         }
 
+        /// <summary>
+        /// Gets the state of the AttachPanel.
+        /// </summary>
+        /// <value>The AttachPanel window state</value>
         public int State
         {
             get
@@ -51,6 +61,11 @@ namespace Tizen.Applications.AttachPanel
                 return state;
             }
         }
+
+        /// <summary>
+        /// Gets the value that indicates whether the AttachPanel is visible.
+        /// </summary>
+        /// <value>visible value of AttachPanel state</value>
         public int Visible
         {
             get
@@ -62,6 +77,33 @@ namespace Tizen.Applications.AttachPanel
             }
         }
 
+        /// <summary>
+        /// Add a content category in the AttachPanel.
+        /// </summary>
+        /// <param name="category">The ContentCategory to be added in the AttachPanel</param>
+        /// <param name="extraData">The AttachPanel send some information using Bundle</param>
+        /// <privilege>http://tizen.org/privilege/mediastorage</privilege>
+        /// <privilege>http://tizen.org/privilege/camera</privilege>
+        /// <privilege>http://tizen.org/privilege/recorder</privilege>
+        /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
+        /// <remarks>
+        /// The caller app has to check the return value of this function.
+        /// Content categories will be shown as the sequence of using AddCategory
+        /// Some contents need time to load it all.
+        /// So, it is needed to use this before the mainloop of Show
+        /// Privileges,
+        /// http://tizen.org/privilege/mediastorage, for using Image or Camera
+        /// http://tizen.org/privilege/camera, for using Camera or TakePicture
+        /// http://tizen.org/privilege/recorder, for using Voice
+        /// http://tizen.org/privilege/appmanager.launch, for adding content categories on the More tab
+        /// Deliver more information to the callee with a bundle if you need.
+        /// http://tizen.org/appcontrol/data/total_count
+        /// http://tizen.org/appcontrol/data/total_size
+        /// </remarks>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when the <paramref name="category"/> is not a valid category</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when application does not have privilege to access this method</exception>
+        /// <exception cref="NotSupportedException">Thrown when the device does not supported the <paramref name="category"/> feature </exception>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is not created yet or already destroyed</exception>
         public void AddCategory(ContentCategory category, Bundle extraData)
         {
             IntPtr bundle = IntPtr.Zero;
@@ -73,12 +115,26 @@ namespace Tizen.Applications.AttachPanel
             checkException(err);
         }
 
+        /// <summary>
+        /// Removes the ContentCategory from the AttachPanel
+        /// </summary>
+        /// <param name="category">The ContentCategory adding in the AttachPanel</param>
+        ///  <exception cref="ArgumentOutOfRangeException">Thrown when the <paramref name="category"/> is not a valid category</exception>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is not created yet or already destroyed</exception>
         public void RemoveCategory(ContentCategory category)
         {
             Interop.AttachPanel.ErrorCode err = Interop.AttachPanel.RemoveCategory(_attachPanel, (int)category);
             checkException(err);
         }
 
+        /// <summary>
+        /// Sets extraData to send to the ContentCategory using a Bundle
+        /// </summary>
+        /// <param name="category">The ContentCategory that some information to be set in the AttachPanel.</param>
+        /// <param name="extraData">The AttachPanel send some information using Bundle</param>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when the <paramref name="category"/> is not a valid category</exception>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is destroyed</exception>
+        /// <exception cref="OutOfMemoryException">Thrown when an attempt to allocate memory fails.</exception>
         public void SetExtraData(ContentCategory category, Bundle extraData)
         {
             IntPtr bundle = IntPtr.Zero;
@@ -90,12 +146,20 @@ namespace Tizen.Applications.AttachPanel
             checkException(err);
         }
 
+        /// <summary>
+        /// Shows the attach panel with animations
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is destroyed</exception>
         public void Show()
         {
             Interop.AttachPanel.ErrorCode err = Interop.AttachPanel.Show(_attachPanel);
             checkException(err);
         }
 
+        /// <summary>
+        /// Shows the attach panel and selects whether or not to animate
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is destroyed</exception>
         public void Show(bool animation)
         {
             if (animation)
@@ -110,12 +174,20 @@ namespace Tizen.Applications.AttachPanel
             }
         }
 
+        /// <summary>
+        /// Hides the attach panel with animations
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is destroyed</exception>
         public void Hide()
         {
             Interop.AttachPanel.ErrorCode err = Interop.AttachPanel.Hide(_attachPanel);
             checkException(err);
         }
 
+        /// <summary>
+        /// Hides the attach panel and selects whether or not to animate
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Thrown when the AttachPanel is destroyed</exception>
         public void Hide(bool animation)
         {
             if (animation)
@@ -130,6 +202,9 @@ namespace Tizen.Applications.AttachPanel
             }
         }
 
+        /// <summary>
+        /// Occurs when reserved events are published from the panel-side.
+        /// </summary>
         public event EventHandler<StateEventArgs> EventChanged
         {
             add
@@ -150,6 +225,9 @@ namespace Tizen.Applications.AttachPanel
             }
         }
 
+        /// <summary>
+        /// Occurs when an user selects and confirms something to attach in the AttachPanel
+        /// </summary>
         public event EventHandler<ResultEventArgs> ResultCallback
         {
             add
diff --git a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanelManager.cs b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanelInternal.cs
similarity index 80%
rename from Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanelManager.cs
rename to Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanelInternal.cs
index e11dc0e..cde510f 100755
--- a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanelManager.cs
+++ b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/AttachPanelInternal.cs
@@ -5,6 +5,14 @@ namespace Tizen.Applications.AttachPanel
 {
     public partial class AttachPanel
     {
+        private static IntPtr _attachPanel;
+
+        private static event EventHandler<StateEventArgs> _eventEventHandler;
+        private static event EventHandler<ResultEventArgs> _resultEventHandler;
+
+        private static Interop.AttachPanel.AttachPanelEventCallback SetEventListener;
+        private static Interop.AttachPanel.AttachPanelResultCallback SetResultListener;
+
         private void StateEventListenStart()
         {
             Interop.AttachPanel.ErrorCode err = 0;
@@ -48,9 +56,9 @@ namespace Tizen.Applications.AttachPanel
             switch (err)
             {
                 case Interop.AttachPanel.ErrorCode.InvalidParameter:
-                    throw new InvalidOperationException("Invalid parameter error at unmanaged code");
+                    throw new ArgumentOutOfRangeException("Invalid parameter error at unmanaged code");
                 case Interop.AttachPanel.ErrorCode.OutOfMemory:
-                    throw new InvalidOperationException("Out of Memory");
+                    throw new OutOfMemoryException("Out of Memory");
                 case Interop.AttachPanel.ErrorCode.PermissionDenied:
                     throw new UnauthorizedAccessException();
                 case Interop.AttachPanel.ErrorCode.AlreadyExists:
@@ -58,7 +66,7 @@ namespace Tizen.Applications.AttachPanel
                 case Interop.AttachPanel.ErrorCode.NotInitialized:
                     throw new InvalidOperationException("Not initialized");
                 case Interop.AttachPanel.ErrorCode.UnsupportedContentCategory:
-                    throw new InvalidOperationException("Unsupported Content Category");
+                    throw new NotSupportedException("Unsupported Content Category");
                 case Interop.AttachPanel.ErrorCode.AlreadyDestroyed:
                     throw new InvalidOperationException("Already Destroyed");
             }
diff --git a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/ResultEventArgs.cs b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/ResultEventArgs.cs
index 70371c7..6628b9d 100755
--- a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/ResultEventArgs.cs
+++ b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/ResultEventArgs.cs
@@ -2,6 +2,9 @@ using System;
 
 namespace Tizen.Applications.AttachPanel
 {
+    /// <summary>
+    /// Class for event arguments of the result event
+    /// </summary>
     public class ResultEventArgs : EventArgs
     {
         private readonly IntPtr _attachPanel;
@@ -19,14 +22,30 @@ namespace Tizen.Applications.AttachPanel
             _userData = userData;
         }
 
+        /// <summary>
+        ///  Property for attach panel object.
+        /// </summary>
         public IntPtr AttachPanel { get { return _attachPanel; } }
 
+        /// <summary>
+        /// Results are from the content category.
+        /// </summary>
         public ContentCategory Category { get { return _category; } }
 
+        /// <summary>
+        /// Property for result
+        /// The caller app has to use ExtraData property to get received data.
+        /// </summary>
         public AppControl Result {  get { return _result; } }
 
+        /// <summary>
+        /// Property for result of AppControl
+        /// </summary>
         public AppControlReplyResult ResultCode { get { return _resultCode; } }
 
+        /// <summary>
+        /// Property for user data
+        /// </summary>
         public IntPtr UserData { get { return _userData; } }
     }
 }
diff --git a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/StateEventArgs.cs b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/StateEventArgs.cs
index 5314225..5354c5f 100755
--- a/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/StateEventArgs.cs
+++ b/Tizen.Applications.AttachPanel/Tizen.Applications.AttachPanel/StateEventArgs.cs
@@ -2,6 +2,9 @@ using System;
 
 namespace Tizen.Applications.AttachPanel
 {
+    /// <summary>
+    /// Class for event arguments of the state event
+    /// </summary>
     public class StateEventArgs : EventArgs
     {
         private readonly IntPtr _attachPanel;
@@ -17,12 +20,25 @@ namespace Tizen.Applications.AttachPanel
             _userData = userData;
         }
 
+        /// <summary>
+        /// Property for attach panel object
+        /// </summary>
         public IntPtr AttachPanel { get { return _attachPanel;  } }
 
+        /// <summary>
+        /// Property for event type.
+        /// </summary>
         public EventType EventType { get { return _eventType;  } }
 
+        /// <summary>
+        /// Additional event information.
+        /// This can be NULL if there are no necessary information.
+        /// </summary>
         public IntPtr EventInfo {  get { return _eventInfo;  } }
 
+        /// <summary>
+        /// Property for user data.
+        /// </summary>
         public IntPtr UserData { get { return _userData; } }
     }
 }