From fa0480394346f3d7a2f459c49a41121cdec267e8 Mon Sep 17 00:00:00 2001
From: Aravinth Manivannan <realaravinth@batsense.net>
Date: Sun, 31 Dec 2023 21:45:15 +0530
Subject: [PATCH] feat: document lib usage

---
 .gitignore                 |  1 +
 README.md                  | 14 +++++++++++-
 src/mcaptcha_api/client.py | 45 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 1fdb66d..174fca6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -160,3 +160,4 @@ cython_debug/
 #.idea/
 tmp/
 .env
+html/
diff --git a/README.md b/README.md
index 16329a8..73afd61 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,19 @@
 
 # mcaptcha_api: Python library to interact with mCaptcha server
 
-### Example
+## Installation
+
+```bash
+pip install mcaptcha_api
+```
+
+## Usage
+
+| Parameter      | Info                                                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `instance_url` | the URL of the mCaptcha instance you are using                                                                        |
+| `sitekey`      | The captcha identifier; can be obtained from dashboard or from widget URL (`http://hostname/widget?sitekey=<sitekey>` |
+| `secret`       | Account secret; can be obtained from mCaptcha dashboard account settings page                                         |
 
 ```python
 mcaptcha = MCaptcha(instance_url=INSTANCE_URL, sitekey=SITEKEY, secret=SECRET)
diff --git a/src/mcaptcha_api/client.py b/src/mcaptcha_api/client.py
index 840c6b4..95568d5 100644
--- a/src/mcaptcha_api/client.py
+++ b/src/mcaptcha_api/client.py
@@ -8,7 +8,41 @@ from requests import Session
 
 
 class MCaptcha:
+    """mCaptcha API client class
+
+    ```
+
+    Attributes
+    ----------
+    instance_url: str
+        the URL of the mCaptcha instance you are using
+    sitekey: str
+        The captcha identifier; can be obtained from dashboard
+        or from widget URL `http://hostname/widget?sitekey=<sitekey>`
+    secret: str
+        Account secret; can be obtained from mCaptcha dashboard
+        account settings page
+
+     Methods
+     -------
+     verify(token)
+     Verify mCaptcha authorization token presented by the visitor
+    """
+
     def __init__(self, instance_url: str, sitekey: str, secret: str):
+        """
+        Parameters
+        ----------
+        instance_url: str
+            the URL of the mCaptcha instance you are using
+        sitekey: str
+            The captcha identifier; can be obtained from dashboard
+            or from widget URL `http://hostname/widget?sitekey=<sitekey>`
+        secret: str
+            Account secret; can be obtained from mCaptcha dashboard
+            account settings page
+        """
+
         self.client = Session()
         self.instance_url = self.__clean_url(instance_url)
         self.sitekey = sitekey
@@ -24,6 +58,17 @@ class MCaptcha:
         return urlunparse((parsed.scheme, parsed.netloc, path, "", "", ""))
 
     def verify(self, token: str) -> bool:
+        """Verify mCaptcha authorization token presented by the visitor
+
+        Parameters
+        ----------
+        token: authorization token presented by the visitor
+
+        Returns
+        -------
+        bool
+            indicating the validity of of the presented authorization presented
+        """
         payload = {"token": token, "key": self.sitekey, "secret": self.secret}
         resp = self.client.post(self.verify_url, json=payload)
         assert resp.status_code == 200