BCSS-20629 - BCSS – Playwright - NHS Number Tools Markdown Improvements (#83)

BCSS – Playwright - NHS Number Tools Markdown Improvements - Utility
Guide - NHSNumberTools.md is updated & also Doc String is updated for
nhs_number_tools.py

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

As per JIRA Ticket BCSS-20629 description, Utility Guide -
NHSNumberTools.md is updated & also Doc String is updated for
nhs_number_tools.py

## Context

<!-- Why is this change required? What problem does it solve? -->
This is required as a part of review activity of BCSS - Playwright -
Update Utility Markdown Documentation

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

- [X] Refactoring (non-breaking change)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [X] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [X] I have followed the code style of the project
- [ ] I have added tests to cover my changes (where appropriate)
- [X] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [X] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

Author: vidhya-chandra1

docs/utility-guides/NHSNumberTools.md

@@ -8,23 +8,51 @@ common functionality that may apply to many services in relation to NHS Number m
 - [Utility Guide: NHS Number Tools](#utility-guide-nhs-number-tools)
   - [Table of Contents](#table-of-contents)
   - [Using the NHS Number Tools class](#using-the-nhs-number-tools-class)
-  - [`spaced_nhs_number()`: Return Spaced NHS Number](#spaced_nhs_number-return-spaced-nhs-number)
+  - [`_nhs_number_checks()`: Checks if the NHS number is valid](#_nhs_number_checks-checks-if-the-nhs-number-is-valid)
     - [Required Arguments](#required-arguments)
+    - [Raises](#raises)
+  - [Example Usage for `_nhs_number_checks()`](#example-usage-for-_nhs_number_checks)
+  - [`spaced_nhs_number()`: Returns Spaced NHS Number](#spaced_nhs_number-returns-spaced-nhs-number)
+    - [Required Arguments](#required-arguments-1)
     - [Returns](#returns)
+  - [Example Usage for `spaced_nhs_number()`](#example-usage-for-spaced_nhs_number)
 
 ## Using the NHS Number Tools class
 
 You can initialise the NHS Number Tools class by using the following code in your test file:
 
-    from utils.nhs_number_tools import NHSNumberTools
+```python
+from utils.nhs_number_tools import NHSNumberTools
+```
 
-## `spaced_nhs_number()`: Return Spaced NHS Number
+## `_nhs_number_checks()`: Checks if the NHS number is valid
 
-The `spaced_nhs_number()` method is designed to take the provided NHS number and return it in a formatted
-string of the format `nnn nnn nnnn`.  It's a static method so can be used in the following way:
+The `_nhs_number_checks()` method does basic checks on NHS number value provided and raises an exception if the number is not valid
 
-    # Return formatted NHS number
-    spaced_nhs_number = NHSNumberTools.spaced_nhs_number("1234567890")
+### Required Arguments
+
+The following are required for `_nhs_number_checks()`:
+
+| Argument   | Format | Description             |
+| ---------- | ------ | ----------------------- |
+| nhs_number | `str`  | The NHS number to check |
+
+### Raises
+
+NHSNumberToolsException: If the NHS number is not numeric or not 10 digits long.
+
+## Example Usage for `_nhs_number_checks()`
+
+```python
+from utils.nhs_number_tools import NHSNumberTools
+    incorrect_nhs_no = "A23456789"
+    NHSNumberTools._nhs_number_checks(incorrect_nhs_no)
+```
+
+## `spaced_nhs_number()`: Returns Spaced NHS Number
+
+The `spaced_nhs_number()` method is designed to take the provided NHS number and return it in a formatted
+string of the format `nnn nnn nnnn`.  It's a static method so can be used in the following way
 
 ### Required Arguments
 
@@ -37,3 +65,11 @@ The following are required for `NHSNumberTools.spaced_nhs_number()`:
 ### Returns
 
 A `str` with the provided NHS number in `nnn nnn nnnn` format. For example, `NHSNumberTools.spaced_nhs_number(1234567890)` would return `123 456 7890`.
+
+## Example Usage for `spaced_nhs_number()`
+
+```python
+from utils.nhs_number_tools import NHSNumberTools
+# Return formatted NHS number
+    spaced_nhs_number = NHSNumberTools.spaced_nhs_number("1234567890")
+```

utils/nhs_number_tools.py

@@ -11,10 +11,16 @@ class NHSNumberTools:
     @staticmethod
     def _nhs_number_checks(nhs_number: str) -> None:
         """
-        This does basic checks on NHS number values provided and raises an exception if the number is not valid.
+        This will validate that the provided NHS number is numeric and exactly 10 digits long.
 
         Args:
-            nhs_number (str): The NHS number to check.
+            nhs_number (str): The NHS number to validate.
+
+        Raises:
+            NHSNumberToolsException: If the NHS number is not numeric or not 10 digits long.
+
+        Returns:
+            None
         """
         if not nhs_number.isnumeric():
             raise NHSNumberToolsException(