Merge pull request #2 from Runninghill/feature/documentation

Create documentation.

Author: Solenoden

CONTRIBUTOR_README.md

@@ -1,8 +1,10 @@
+![Runninghill Logo](./docs/runninghill.png "Runninghill")
+
 # Angular South African Form Validators
 
 A set of South African specific validators for Angular forms.
 
-# Getting Started
+# Getting Started🏁
 
 1. Clone the repo.
 
@@ -14,34 +16,26 @@ A set of South African specific validators for Angular forms.
 
 3. Make your changes.
 
-4. Ensure that your changes are of good quality and comply with our [Coding Standards](#coding-standards).
+4. Ensure that your changes are of good quality.
 
 5. Commit your changes and submit a PR to merge your changes into `main`.
 
-# NPM Scripts
+# NPM Scripts📜
 
 To check eslint, run command `npm run lint`.
 
 To check unit tests, run command `npm run test`.
 
-# Contribute
+# Contribute🌳
 
 Ensure you work out of the project itself (`projects/rh-rsa-form-validators`) and not the Angular workspace
 
 Always make the code better, if you see errors, please fix them. 
 
 Add tests and try to move the code coverage up to 90%. 
 
-Update the [usage documentation](/projects/rh-rsa-form-validators/README.md).
+Update the [usage documentation](https://github.com/Runninghill/rh-angular-rsa-form-validators/blob/main/projects/rh-rsa-form-validators/README.md).
 
 Bump the version number according to [semantic versioning](https://semver.org/#semantic-versioning-200).
 
-Adhere to the [Coding Standards](#coding-standards).
-
 Only the classes and models exported in `public-api.ts` will be exposed through the package.
-
-# Coding Standards
-
-TODO: Define coding standards
-
-- Form validators should not make the form control required.

docs/runninghill.png

@@ -9,6 +9,7 @@
     "lint": "ng lint"
   },
   "private": true,
+  "readme": "CONTRIBUTOR_README",
   "dependencies": {
     "@angular/animations": "~10.2.0",
     "@angular/common": "~10.2.0",

package.json

@@ -1,21 +1,68 @@
+![Runninghill Logo](../../docs/runninghill.png "Runninghill")
+
 # Angular South African Form Validators
 
 A set of South African specific validators for Angular forms.
 
-TODO: Add the Runninghill and Angular logos as well as some emojis
-
-# Getting Started
+# Getting Started🏁
 
 If you plan on contributing to the package please read the contributor readme.
 
 1. Run `npm install rh-angular-rsa-form-validators` in your Angular project.
 
 2. Import and use the exposed classes to validate your Angular form controls.
 
-# Usage
+# Usage💡
+
+To begin validating your South African specific form fields, start by importing
+the _RsaFormValidators_ class.
+
+```Javascript
+import { RsaFormValidator } from 'rh-angular-rsa-form-validators'
+```
+
+Add the appropriate validator to your form control(s).
+
+```Javascript
+// When creating your form
+this.form = this.formBuilder.group({
+    name: ['', Validators.required],
+    mobileNumber: ['', [Validators.required, RsaFormValidator.phoneNumber(false, true)]],
+    workNumber: ['']
+})
+
+// After the form is already created
+this.form.controls['workNumber'].setValidators([RsaFormValidators.phoneNumber(false, true)])
+```
+
+To determine if the form control passed the validation, check the errors object on the form control.
+
+RsaFormValidator error objects on form controls will always be the name of the validator, 
+prefixed with 'rsa' eg; for the rsa phone number validator, the error object is `rsaPhoneNumber`
+(rsa + phoneNumber = rsaPhoneNumber) 
+
+```Javascript
+if (this.form.controls['mobileNumber'].errors.rsaPhoneNumber)
+    errorMessage = 'Mobile number must be a valid South African phone number.'
+```
+
+# API Reference📖
+
+### RsaFormValidator
+
+Contains form control validators used to validate South African specific form fields.
+
+[_source code_](https://github.com/Runninghill/rh-angular-rsa-form-validators/blob/main/projects/rh-rsa-form-validators/src/lib/validators/rsa-form-validator.ts)
+
+#### Methods
+
+##### phoneNumber(allowCountryCode, allowSpaces)
 
-TODO: Fill out usage section
+Returns a validator which determines if a form control is a valid South African phone number.
 
-# API Reference
+Parameters
 
-TODO: Fill out api reference section
+|Name|Type|Description|Default|
+|----|----|-----------|-------|
+|allowCountryCode|boolean|determines if the phone number is allowed to contain the South African country code (+27)|true|
+|allowSpaces|boolean|determines if a phone number is allowed to contain spaces|true|

projects/rh-rsa-form-validators/README.md

@@ -40,5 +40,5 @@
   "bugs": {
     "url": "https://github.com/Runninghill/rh-angular-rsa-form-validators/issues"
   },
-  "homepage": "https://github.com/Runninghill/rh-angular-rsa-form-validators#readme"
+  "homepage": "https://github.com/Runninghill/rh-angular-rsa-form-validators/projects/rh-rsa-form-validators#readme"
 }