[Tizen.Security.SecureRepository] Enhancements of API description

src/Tizen.Security.SecureRepository/Tizen.Security.SecureRepository/Certificate.cs

@@ -21,7 +21,7 @@
 namespace Tizen.Security.SecureRepository
 {
     /// <summary>
-    /// The class that represents a certificate.
+    /// Represents a certificate.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class Certificate
@@ -30,14 +30,12 @@ public class Certificate
         /// Loads Certificate from the given file path.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="filePath">The path of certificate file to be loaded.</param>
+        /// <param name="filePath">Path of certificate file to be loaded.</param>
         /// <returns>Loaded certificate class instance.</returns>
-        /// <exception cref="ArgumentNullException">
-        /// The filePath should not be null
-        /// </exception>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="filePath"/> is null.</exception>
         /// <exception cref="InvalidOperationException">
-        /// Invalid certificate file format. Provided file path does not exist or
-        /// cannot be accessed.
+        /// Thrown when a certificate has invalid file format.
+        /// Thrown when provided file path does not exist or cannot be accessed.
         /// </exception>
         static public Certificate Load(string filePath)
         {
@@ -54,11 +52,11 @@ static public Certificate Load(string filePath)
         }
 
         /// <summary>
-        /// A constructor of Certificate that takes the binary and its format.
+        /// Initializes an instance of Certificate class with a binary and its data format.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="binary">The binary data of a certificate.</param>
-        /// <param name="format">The format of the binary data.</param>
+        /// <param name="binary">Binary data of a certificate.</param>
+        /// <param name="format">Format of the binary data.</param>
         public Certificate(byte[] binary, DataFormat format)
         {
             this.Binary = binary;
@@ -101,17 +99,23 @@ internal IntPtr GetHandle()
         }
 
         /// <summary>
-        /// The binary value of a certificate.
+        /// Gets and sets binary value of a certificate.
         /// </summary>
+        /// <value>
+        /// Binary value of a certificate.
+        /// </value>
         /// <since_tizen> 3 </since_tizen>
         public byte[] Binary
         {
             get; set;
         }
 
         /// <summary>
-        /// The format of the binary value.
+        /// Gets and sets format of the binary value.
         /// </summary>
+        /// <value>
+        /// Format of the binary value.
+        /// </value>
         /// <since_tizen> 3 </since_tizen>
         public DataFormat Format
         {

src/Tizen.Security.SecureRepository/Tizen.Security.SecureRepository/CertificateManager.cs

@@ -21,7 +21,7 @@
 namespace Tizen.Security.SecureRepository
 {
     /// <summary>
-    /// This class provides the methods handling certificates.
+    /// Provides methods that handle certificates.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class CertificateManager : Manager
@@ -30,22 +30,22 @@ public class CertificateManager : Manager
         /// Gets a certificate from the secure repository.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="alias">The name of a certificate to be retrieved.</param>
-        /// <param name="password">
-        /// The password used in decrypting a certificate value. If password of
-        /// policy is provided in SaveCertificate(), the same password should be
-        /// provided.
-        /// </param>
-        /// <returns>A certificate specified by alias.</returns>
+        /// <remarks>
+        /// If password of policy is provided in SaveCertificate(),
+        /// the same password should be provided.
+        /// </remarks>
+        /// <param name="alias">Name of a certificate to be retrieved.</param>
+        /// <param name="password">Password used in decrypting a certificate value.</param>
+        /// <returns>Certificate specified by alias.</returns>
         /// <exception cref="ArgumentNullException">
-        /// The alias argument is null.
+        /// Thrown when <paramref name="alias"/> argument is null.
         /// </exception>
         /// <exception cref="ArgumentException">
-        /// The alias argument is in an invalid format.
+        /// Thrown when <paramref name="alias"/> argument has an invalid format.
         /// </exception>
         /// <exception cref="InvalidOperationException">
-        /// The certificate does not exist with the alias or certificate-protecting
-        /// password isn't matched.
+        /// Thrown when a certificate does not exist with the <paramref name="alias"/> or certificate-protecting
+        /// password does not match.
         /// </exception>
         static public Certificate Get(string alias, string password)
         {
@@ -69,11 +69,11 @@ static public Certificate Get(string alias, string password)
         }
 
         /// <summary>
-        /// Gets all aliases of certificates, which the client can access.
+        /// Gets all aliases of certificates accessible by the client.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <returns>All aliases of certificates, which the client can access.</returns>
-        /// <exception cref="ArgumentException">No alias to get.</exception>
+        /// <returns>All aliases of certificates accessible by the client.</returns>
+        /// <exception cref="ArgumentException">Thrown when there's no alias to get.</exception>
         static public IEnumerable<string> GetAliases()
         {
             IntPtr ptr = IntPtr.Zero;
@@ -96,19 +96,15 @@ static public IEnumerable<string> GetAliases()
         /// Stores a certificate inside the secure repository based on the provided policy.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="alias">The name of a certificate to be stored.</param>
-        /// <param name="cert">The certificate's binary value to be stored.</param>
-        /// <param name="policy">
-        /// The policy about how to store a certificate securely.
-        /// </param>
-        /// <exception cref="ArgumentNullException">
-        /// Any of argument is null.
-        /// </exception>
+        /// <param name="alias">Name of a certificate to be stored.</param>
+        /// <param name="cert">Certificate's binary value to be stored.</param>
+        /// <param name="policy">Certificate storing policy.</param>
+        /// <exception cref="ArgumentNullException">Thrown when any argument is null.</exception>
         /// <exception cref="ArgumentException">
-        /// The alias argument is in the invalid format. cert argument is in the invalid format.
+        /// Thrown when <paramref name="alias"/> or <paramref name="cert"/> argument has an invalid format.
         /// </exception>
         /// <exception cref="InvalidOperationException">
-        /// The certificate with alias already exist.
+        /// Thrown when a certificate with given <paramref name="alias"/> already exists.
         /// </exception>
         static public void Save(string alias, Certificate cert, Policy policy)
         {
@@ -125,30 +121,29 @@ static public void Save(string alias, Certificate cert, Policy policy)
         /// Verifies a certificate chain and returns that chain.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="certificate">The certificate to be verified.</param>
+        /// <remarks>
+        /// Trusted root certificate of the chain should exist in the system's
+        /// certificate storage.
+        /// </remarks>
+        /// <remarks>
+        /// Trusted root certificate of the chain in the system's certificate storage
+        /// is added to the certificate chain.
+        /// </remarks>
+        /// <param name="certificate">Certificate to be verified.</param>
         /// <param name="untrustedCertificates">
-        /// The untrusted CA certificates to be used in verifying a certificate chain.
+        /// Untrusted CA certificates to be used in verifying a certificate chain.
         /// </param>
-        /// <returns>A newly created certificate chain.</returns>
+        /// <returns>Newly created certificate chain.</returns>
         /// <exception cref="ArgumentNullException">
-        /// The certificate argument is null.
+        /// Thrown when a <paramref name="certificate"/> argument is null.
         /// </exception>
         /// <exception cref="ArgumentException">
-        /// Some of the certificates in arguments are invalid.
-        /// </exception>
+        /// Thrown when any of the provided certificates is invalid.</exception>
         /// <exception cref="InvalidOperationException">
-        /// Some of the certificates in arguments are expired or not valid yet.
-        /// Certificate cannot build chain.
-        /// The root certificate is not in the trusted system certificate store.
+        /// Thrown when any of the provided certificates is expired or not valid yet.
+        /// Thrown when certificate cannot build a chain.
+        /// Thrown when root certificate is not in the trusted system certificate store.
         /// </exception>
-        /// <remarks>
-        /// The trusted root certificate of the chain should exist in the system's
-        /// certificate storage.
-        /// </remarks>
-        /// <remarks>
-        /// The trusted root certificate of the chain in the system's certificate storage
-        /// is added to the certificate chain.
-        /// </remarks>
         static public IEnumerable<Certificate> GetCertificateChain(
             Certificate certificate, IEnumerable<Certificate> untrustedCertificates)
         {
@@ -188,33 +183,33 @@ static public IEnumerable<Certificate> GetCertificateChain(
         /// trusted and untrusted CA certificates.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="certificate">The certificate to be verified.</param>
+        /// <remarks>
+        /// Trusted root certificate of the chain in the system's certificate storage
+        /// is added to the certificate chain.
+        /// </remarks>
+        /// <param name="certificate">Certificate to be verified.</param>
         /// <param name="untrustedCertificates">
-        /// The untrusted CA certificates to be used in verifying a certificate chain.
+        /// Untrusted CA certificates to be used in verifying a certificate chain.
         /// </param>
         /// <param name="trustedCertificates">
-        /// The trusted CA certificates to be used in verifying a certificate chain.
+        /// Trusted CA certificates to be used in verifying a certificate chain.
         /// </param>
         /// <param name="useTrustedSystemCertificates">
-        /// The flag indicating the use of the trusted root certificates in the
+        /// Flag indicating the use of the trusted root certificates in the
         /// system's certificate storage.
         /// </param>
-        /// <returns>A newly created certificate chain.</returns>
+        /// <returns>Newly created certificate chain.</returns>
         /// <exception cref="ArgumentNullException">
-        /// The certificate argument is null.
+        /// Thrown when <paramref name="certificate"/> argument is null.
         /// </exception>
         /// <exception cref="ArgumentException">
-        /// Some of the certificates in arguments are invalid.
+        /// Thrown when any of the provided certificates is invalid.
         /// </exception>
         /// <exception cref="InvalidOperationException">
-        /// Some of the certificates in arguments are expired or not valid yet.
-        /// Certificate cannot build chain.
-        /// The root certificate is not in the trusted system certificate store.
+        /// Thrown when any of the provided certificates is expired or not valid yet.
+        /// Thrown when certificate cannot build a chain.
+        /// Thrown when root certificate is not in the trusted system certificate store.
         /// </exception>
-        /// <remarks>
-        /// The trusted root certificate of the chain in the system's certificate storage
-        /// is added to the certificate chain.
-        /// </remarks>
         static public IEnumerable<Certificate> GetCertificateChain(
             Certificate certificate, IEnumerable<Certificate> untrustedCertificates,
             IEnumerable<Certificate> trustedCertificates,
@@ -256,21 +251,19 @@ static public IEnumerable<Certificate> GetCertificateChain(
         }
 
         /// <summary>
-        /// Perform OCSP, which checks whether the certificate is revoked or not.
+        /// [Obsolete("Please do not use! this will be deprecated")]
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <param name="certificateChain">
-        /// Valid certificate chain to perform the OCSP check.
-        /// </param>
-        /// <returns>A status result of the OCSP check.</returns>
+        /// <param name="certificateChain">Valid certificate chain to perform the OCSP check.</param>
+        /// <returns>Status result of the OCSP check.</returns>
         /// <exception cref="ArgumentNullException">
-        /// The certificateChain argument is null.
+        /// Thrown when <paramref name="certificateChain"/> argument is null.
         /// </exception>
         /// <exception cref="ArgumentException">
-        /// The certificateChain is not valid chain or certificate.
+        /// Thrown when <paramref name="certificateChain"/> is not a valid chain or certificate.
         /// </exception>
         /// <exception cref="InvalidOperationException">
-        /// Some of the certificates in chain are expired or not valid yet.
+        /// Thrown when any of the certificates in chain is expired or not valid yet.
         /// </exception>
         [Obsolete("Please do not use! This will be deprecated with API9 and removed with API11! Please use raw OpenSSL instead!")]
         static public OcspStatus CheckOcsp(IEnumerable<Certificate> certificateChain)

src/Tizen.Security.SecureRepository/Tizen.Security.SecureRepository/Crypto/AesCbcCipherParameters.cs

@@ -17,16 +17,16 @@
 namespace Tizen.Security.SecureRepository.Crypto
 {
     /// <summary>
-    /// A class for holding parameters for the AES algorithm with the CBC mode.
+    /// Holds parameters for the AES algorithm with the CBC mode.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class AesCbcCipherParameters : AesCipherParameters
     {
         /// <summary>
-        /// A default constructor.
+        /// Initializes an instance of AesCbcCipherParameters class.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <remarks>The CipherAlgorithmType in CipherParameters is set to CipherAlgorithmType.AesCbc.</remarks>
+        /// <remarks>CipherAlgorithmType in CipherParameters is set to CipherAlgorithmType.AesCbc.</remarks>
         public AesCbcCipherParameters() : base(CipherAlgorithmType.AesCbc)
         {
         }

src/Tizen.Security.SecureRepository/Tizen.Security.SecureRepository/Crypto/AesCfbCipherParameters.cs

@@ -17,16 +17,16 @@
 namespace Tizen.Security.SecureRepository.Crypto
 {
     /// <summary>
-    /// A class for holding parameters for the AES algorithm with the CFB mode.
+    /// Holds parameters for the AES algorithm with the CFB mode.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class AesCfbCipherParameters : AesCipherParameters
     {
         /// <summary>
-        /// A default constructor.
+        /// Initializes an instance of AesCfbCipherParameters class.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <remarks>The CipherAlgorithmType in CipherParameters is set to CipherAlgorithmType.AesCfb.</remarks>
+        /// <remarks>CipherAlgorithmType in CipherParameters is set to CipherAlgorithmType.AesCfb.</remarks>
         public AesCfbCipherParameters() : base(CipherAlgorithmType.AesCfb)
         {
         }

src/Tizen.Security.SecureRepository/Tizen.Security.SecureRepository/Crypto/AesCipherParameters.cs

@@ -17,14 +17,17 @@
 namespace Tizen.Security.SecureRepository.Crypto
 {
     /// <summary>
-    /// An abstract class for holding parameters for the AES algorithm.
+    /// Holds parameters for the AES algorithm.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public abstract class AesCipherParameters : CipherParameters
     {
         /// <summary>
-        /// An initialization vector.
+        /// Gets and sets initialization vector.
         /// </summary>
+        /// <value>
+        /// Initialization vector for AES cipher.
+        /// </value>
         /// <since_tizen> 3 </since_tizen>
         public byte[] IV
         {

src/Tizen.Security.SecureRepository/Tizen.Security.SecureRepository/Crypto/AesCtrCipherParameters.cs

@@ -19,26 +19,28 @@
 namespace Tizen.Security.SecureRepository.Crypto
 {
     /// <summary>
-    /// A class for holding parameters for the AES algorithm with the counter mode.
+    /// Holds parameters for the AES algorithm with the counter mode.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class AesCtrCipherParameters : AesCipherParameters
     {
         /// <summary>
-        /// A default constructor.
+        /// Initializes an instance of AesCtrCipherParameters class.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
-        /// <remarks>The CipherAlgorithmType in CipherParameters is set to CipherAlgorithmType.AesCtr.</remarks>
+        /// <remarks>CipherAlgorithmType in CipherParameters is set to CipherAlgorithmType.AesCtr.</remarks>
         public AesCtrCipherParameters() : base(CipherAlgorithmType.AesCtr)
         {
         }
 
         /// <summary>
-        /// Length of the counter block in bits.
+        /// Gets and sets the length of the counter block in bits.
         /// </summary>
+        /// <value>
+        /// Length of the counter block in bits. Optional, only 128b is supported at the moment.
+        /// </value>
         /// <since_tizen> 3 </since_tizen>
-        /// <remarks>Optional, only 128b is supported at the moment.</remarks>
-        /// <exception cref="ArgumentOutOfRangeException">The value should be positive.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when value is not positive.</exception>
         public long CounterLength
         {
             get