Merge pull request #202 from ldclakmal/dev-docs

Improve API docs
ballerina-platform · May 21, 2021 · 73341df · 73341df
2 parents 066daa4 + c768e27
commit 73341df
Show file tree

Hide file tree

Showing 3 changed files with 9 additions and 10 deletions.
diff --git a/oauth2-ballerina/client_oauth2_provider.bal b/oauth2-ballerina/client_oauth2_provider.bal
@@ -17,7 +17,7 @@
 import ballerina/log;
 import ballerina/time;
 
-# The data structure, which is used to configure the OAuth2 client credentials grant type.
+# Represents the data structure, which is used to configure the OAuth2 client credentials grant type.
 #
 # + tokenUrl - Token URL for the authorization endpoint
 # + clientId - Client ID for the client credentials grant authentication
@@ -40,7 +40,7 @@ public type ClientCredentialsGrantConfig record {|
     ClientConfiguration clientConfig = {};
 |};
 
-# The data structure, which is used to configure the OAuth2 password grant type.
+# Represents the data structure, which is used to configure the OAuth2 password grant type.
 #
 # + tokenUrl - Token URL for the authorization endpoint
 # + username - Username for the password grant authentication
@@ -75,7 +75,7 @@ public type PasswordGrantConfig record {|
     ClientConfiguration clientConfig = {};
 |};
 
-# The data structure, which can be used to configure OAuth2 refresh token grant type.
+# Represents the data structure, which is used to configure the OAuth2 refresh token grant type.
 #
 # + refreshUrl - Refresh token URL for the refresh token server
 # + refreshToken - Refresh token for the refresh token server

diff --git a/oauth2-ballerina/listener_oauth2_provider.bal b/oauth2-ballerina/listener_oauth2_provider.bal
@@ -78,9 +78,8 @@ const string AUD = "aud";
 const string ISS = "iss";
 const string JTI = "jti";
 
-# Represents the client OAuth2 provider, which is used to generate the OAuth2 access tokens using the configured OAuth2
-# authorization server configurations. This supports the client credentials grant type, password grant type, and
-# refresh token grant type.
+# Represents the listener OAuth2 provider, which is used to validate the received credential (access token) by
+# calling the configured OAuth2 introspection server.
 # ```ballerina
 # oauth2:IntrospectionConfig config = {
 #     url: "https://localhost:9196/oauth2/token/introspect"

diff --git a/oauth2-ballerina/oauth2_commons.bal b/oauth2-ballerina/oauth2_commons.bal
@@ -32,10 +32,10 @@ public type ClientConfiguration record {|
     SecureSocket secureSocket?;
 |};
 
-# Defines the authentication configuration types for the HTTP client used for token introspection.
+# Represents the the authentication configuration types for the HTTP client used for token introspection.
 public type ClientAuth ClientCredentialsGrantConfig|PasswordGrantConfig|RefreshTokenGrantConfig;
 
-# Represents HTTP versions.
+# Represents the HTTP versions.
 public enum HttpVersion {
     HTTP_1_1,
     HTTP_2
@@ -52,7 +52,7 @@ public type SecureSocket record {|
     crypto:KeyStore|CertKey key?;
 |};
 
-# Represents combination of certificate, private key and private key password if encrypted.
+# Represents the combination of the certificate file path, private key file path, and private key password if encrypted.
 #
 # + certFile - A file containing the certificate
 # + keyFile - A file containing the private key
@@ -63,7 +63,7 @@ public type CertKey record {|
    string keyPassword?;
 |};
 
-# Represents HTTP versions.
+# Represents the credential-bearing methods.
 public enum CredentialBearer {
     AUTH_HEADER_BEARER,
     POST_BODY_BEARER