diff --git a/example/lib/main.dart b/example/lib/main.dart
index 92519ce..afd41d8 100644
--- a/example/lib/main.dart
+++ b/example/lib/main.dart
@@ -1,12 +1,12 @@
 import 'package:fal_client/client.dart';
 import 'package:flutter/material.dart';
 
-// final fal = FalClient.withProxy("http://localhost:3333/api/_fal/proxy");
+// You can use the proxyUrl to protect your credentials in production.
+// final fal = FalClient.withProxy("http://localhost:3333/api/fal/proxy");
 
 // You can also use the credentials locally for development, but make sure
 // you protected your credentials behind a proxy in production.
-final fal = FalClient.withCredentials(
-    "adf7f57f-d316-41c3-bb12-552356340cfe:d16be5f12c0091c1dc22696a2fd07c9b");
+final fal = FalClient.withCredentials("fal_key_id:fal_key_secret");
 
 void main() {
   runApp(const MyApp());
diff --git a/lib/client.dart b/lib/client.dart
index 68a6e43..6425588 100644
--- a/lib/client.dart
+++ b/lib/client.dart
@@ -6,11 +6,44 @@ import './http.dart';
 import './queue.dart';
 import './storage.dart';
 
+/// The main client class that provides access to simple API model usage,
+/// as well as access to the [queue] and [storage] APIs.
+///
+/// Example:
+///
+/// ```dart
+/// import 'package:fal_client/client.dart';
+///
+/// final fal = FalClient.withCredentials("fal_key_id:fal_key_secret");
+///
+/// void main() async {
+///   // check https://fal.ai/models for the available models
+///   final result = await fal.subscribe('text-to-image', input: {
+///     'prompt': 'a cute shih-tzu puppy',
+///     'model_name': 'stabilityai/stable-diffusion-xl-base-1.0',
+///   });
+///   print(result);
+/// }
+/// ```
 abstract class Client {
+  /// The queue client with specific methods to interact with the queue API.
+  ///
+  /// **Note:** that the [subscribe] method is a convenience method that uses the
+  /// [queue] client to submit a request and poll for the result.
   Queue get queue;
 
+  /// The storage client with specific methods to interact with the storage API.
+  ///
+  /// **Note:** both [run] and [subscribe] auto-upload files using the [storage]
+  /// when an [XFile] is passed as an input property value.
   Storage get storage;
 
+  /// Sends a request to the given [id], an optional [path]. This method
+  /// is a direct request to the model API and it waits for the processing
+  /// to complete before returning the result.
+  ///
+  /// This is useful for short running requests, but it's not recommended for
+  /// long running requests, for those see [submit].
   Future<Map<String, dynamic>> run(
     String id, {
     String method = 'post',
@@ -18,6 +51,11 @@ abstract class Client {
     Map<String, dynamic>? input,
   });
 
+  /// Submits a request to the given [id], an optional [path]. This method
+  /// uses the [queue] API to submit the request and poll for the result.
+  ///
+  /// This is useful for long running requests, and it's the preffered way
+  /// to interact with the model APIs.
   Future<Map<String, dynamic>> subscribe(
     String id, {
     String path = '',
diff --git a/lib/queue.dart b/lib/queue.dart
index d2126f6..9e100b4 100644
--- a/lib/queue.dart
+++ b/lib/queue.dart
@@ -53,6 +53,7 @@ abstract class QueueStatus {
   }
 }
 
+/// Indicates that the queue is currently processing the request.
 class InProgressStatus extends QueueStatus {
   List<RequestLog> logs;
 
@@ -71,6 +72,7 @@ class InProgressStatus extends QueueStatus {
   }
 }
 
+/// Indicates that the request has been completed and contains the [logs].
 class CompletedStatus extends QueueStatus {
   List<RequestLog> logs;
 
@@ -89,6 +91,7 @@ class CompletedStatus extends QueueStatus {
   }
 }
 
+/// Indicates that the request is still in the queue and contains the [queuePosition].
 class InQueueStatus extends QueueStatus {
   int queuePosition;
 
@@ -105,19 +108,27 @@ class InQueueStatus extends QueueStatus {
   }
 }
 
+/// This establishes the contract of the client with the queue API.
 abstract class Queue {
+  /// Submits a request to the given [id], an optional [path]. This method
+  /// uses the [queue] API to initiate the request. Next you need to rely on
+  /// [status] and [result] to poll for the result.
   Future<EnqueueResult> submit(
     String id, {
     String path = '',
     Map<String, dynamic>? input,
   });
 
+  /// Checks the queue for the status of the request with the given [requestId].
+  /// See [QueueStatus] for the different statuses.
   Future<QueueStatus> status(
     String id, {
     required String requestId,
     bool logs,
   });
 
+  /// Retrieves the result of the request with the given [requestId]
+  /// once the queue status is [CompletedStatus].
   Future<Map<String, dynamic>> result(String id, {required String requestId});
 }