Documentation improvements

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Current Behaviour
+
+<!-- Provide a detailed description of how it behaves currently. -->
+
+## Expected Behaviour
+
+<!-- Provide a detailed description of how you expected it to behave. -->
+
+## Steps to Reproduce the Problem
+
+1.
+1.
+1.
+
+## Context
+
+<!-- Provide a description of your environment where you encountered this behaviour. -->
+
+- Version:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Issue
+
+<!-- Provide a reference to the issue that this change is going to address -->
+<!-- E.g. #12 Issue title here -->
+
+#[issue-no] [issue title]
+
+## Changes
+
+<!-- Provide a detailed description of the changes proposed in this PR -->
+
+1.
+1.
+1.

CONTRIBUTING.md

@@ -1,11 +1,11 @@
-# Contributing to ID PASS SmartScanner
+# Contributing to SmartScanner Core
 
-Thank you for your interest to contribute to ID PASS SmartScanner! We want to make contributing to this project as easy as possible, whether it's:
+Thank you for your interest to contribute to SmartScanner Core! We want to make contributing to this project as easy as possible, whether it's:
 
 - Reporting a bug
 - Discussing the current state of the code
 - Submitting a fix
-- Propositing new features
+- Proposing new features
 
 ## We develop with GitHub
 
@@ -23,7 +23,7 @@ We use [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/git
 
 ## Reporting bugs
 
-We use [GitHub issues](https://github.com/idpass/idpass-smart-scanner-core/issues) to track bugs. Report a bug by [opening a new issue](https://github.com/idpass/idpass-smart-scanner-core/issues/new).
+We use [GitHub issues](https://github.com/idpass/smartscanner-core/issues) to track bugs. Report a bug by [opening a new issue](https://github.com/idpass/smartscanner-core/issues/new).
 
 Write bug reports with detail, background, and sample code. An issue template is provided when opening a new issue, make sure to provide all the requested information to make it easier to address the issue.
 

README.md

@@ -1,86 +1,101 @@
-# ID PASS SmartScanner
-This is the core repository of the ID PASS SmartScanner that provides developers with an API that enables them to scan MRZ, Barcode, and ID PASS Lite cards.
+# SmartScanner Core
 
-It provides 2 projects:
-- Android library that can be integrated into other projects
-- Android App
+An Android library for scanning MRZ, Barcode, and [ID PASS Lite](https://github.com/idpass/idpass-lite) cards.
 
-## Setting Up
----------------
-```bash
-# 1. Clone this repository.
-git clone https://github.com/idpass/idpass-smart-scanner-core.git
+## Features
 
-# 2. Enter your newly-cloned folder.
-cd idpass-smart-scanner-core
+- Scan MRZ
+- Scan Barcode
+- Scan [ID PASS Lite](https://github.com/idpass/idpass-lite)
+- Supports Intent Call Out (ODK & Non-ODK)
 
-```
+This repository also includes an Android [demo app](app) to test what the library can do.
 
-## Building
-```bash
-./gradlew build
-```
+## Related projects
 
-## Features
-- Scan MRZ
-- Scan Barcode
-- Scan ID PASS Lite
-- Intent Call Out support (ODK/Non-ODK)
-- Plugin Integration for [Capacitor](https://github.com/idpass/idpass-smart-scanner-capacitor)/[Cordova](https://github.com/idpass/idpass-smart-scanner-cordova)
+- [smartscanner-android](https://github.com/idpass/smartscanner-android) - Provides convenience methods to simplify the SmartScanner intent call out process
+- [smartscanner-capacitor](https://github.com/idpass/smartscanner-capacitor) - SmartScanner [Capacitor](https://capacitorjs.com/) plugin
+- [smartscanner-cordova](https://github.com/idpass/smartscanner-cordova) - SmartScanner [Cordova](https://cordova.apache.org/) plugin
 
-## Quickstart
-This library is used to scan MRZ, Barcode, and ID PASS Lite cards. This also has an embedded standalone `app` for testing purposes
+## Installation
 
-<!--
-### 1. Install
-Declare Maven Central repository in the dependency configuration. For example, in `build.gradle`:
+Declare Maven Central repository in the dependency configuration, then add this library in the dependencies. An example using `build.gradle`:
 
 ```groovy
 repositories {
-    mavenCentral()
+  mavenCentral()
 }
 
 dependencies {
-    implementation "org.idpass:idpass-smartscanner:0.0.1-SNAPSHOT"
+  implementation "org.idpass:idpass-smartscanner:0.0.1-SNAPSHOT"
 }
 ```
--->
-### 2. Usage
----------------
-App Intent Call out
 
-Call scanner using the ff intent actions:
-- `"org.idpass.smartscanner.MRZ_SCAN"`
-- `"org.idpass.smartscanner.BARCODE_SCAN"`
-- `"org.idpass.smartscanner.IDPASS_LITE_SCAN"`
+If you want to build this library from source, instructions to do so can be found in the [Building from source](https://github.com/idpass/smartscanner-core/wiki/Building-from-source) wiki page.
+
+## Usage
+
+The following table shows the intent actions available for each operation available in the library, both in ODK and Non-ODK:
+
+| Scan Operation |                                            ODK |                                    Non-ODK |
+| -------------- | ---------------------------------------------- | ------------------------------------------ |
+| MRZ            | `org.idpass.smartscanner.odk.MRZ_SCAN`         | `org.idpass.smartscanner.MRZ_SCAN`         |
+| Barcode        | `org.idpass.smartscanner.odk.BARCODE_SCAN`     | `org.idpass.smartscanner.BARCODE_SCAN`     |
+| ID PASS Lite   | `org.idpass.smartscanner.odk.IDPASS_LITE_SCAN` | `org.idpass.smartscanner.IDPASS_LITE_SCAN` |
 
-ODK Support can be called using the ff intent actions:
-- `"org.idpass.smartscanner.odk.MRZ_SCAN"`
-- `"org.idpass.smartscanner.odk.BARCODE_SCAN"`
-- `"org.idpass.smartscanner.odk.IDPASS_LITE_SCAN"`
+To perform an operation, create an intent for the desired operation. This example shows how to call an intent to scan an MRZ (ODK):
 
 ```kotlin
-    // Sample SmartScanner MRZ intent call out
-    val OP_SCANNER = 1001 // Activity request code
+import android.app.Activity
+import android.content.ActivityNotFoundException
+import android.content.Intent
+import androidx.appcompat.app.AppCompatActivity
+
+class MainActivity : AppCompatActivity() {
+
+  private const val OP_SCANNER = 1001 // Activity request code
+
+  override fun onStart() {
+    super.onStart()
+
     try {
-        val action = "org.idpass.smartscanner.MRZ_SCAN"
-        val intent = Intent(action)
-        startActivityForResult(intent, OP_SCANNER)
+      val action = "org.idpass.smartscanner.odk.MRZ_SCAN"
+      val intent = Intent(action)
+      startActivityForResult(intent, OP_SCANNER)
     } catch (ex: ActivityNotFoundException) {
-        ex.printStackTrace()
-        Log.e(TAG, "smart scanner is not installed!")
+      ex.printStackTrace()
     }
+  }
+
+  public override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
+    super.onActivityResult(requestCode, resultCode, intent)
 
-    // Get Result from the ActivityResult via Bundle
-        public override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
-        super.onActivityResult(requestCode, resultCode, intent)
-        if (requestCode == OP_SCANNER) {
-            Log.d(TAG, "Plugin post SmartScanner Activity resultCode $resultCode")
-            if (resultCode == RESULT_OK) {
-                val bundle =intent?.getBundleExtra("result")
-            }
-        }
+    if (requestCode == OP_SCANNER) {
+      if (resultCode == Activity.RESULT_OK) {
+        val bundle = intent?.getBundleExtra("result")
+      }
     }
+  }
+
+}
+```
+
+The `bundle` variable is a [`Bundle`](https://developer.android.com/reference/kotlin/android/os/Bundle) object containing the scan results. For example, the scanned surname can be obtained through:
+
+```kotlin
+val surname = bundle.getString("surname")
 ```
 
-For convenience, you may use the [smartscanner-android-api](https://github.com/idpass/smartscanner-android-api) which will simplify the app intent call out process.
+Refer to the [Result fields reference](https://github.com/idpass/smartscanner-core/wiki/Result-fields-reference) for the different fields available from the scan results.
+
+Refer to the [API Reference](https://github.com/idpass/smartscanner-core/wiki/API-Reference) for complete information about each scan operation and the different options available.
+
+Finally, for convenience we recommend using the [smartscanner-android](https://github.com/idpass/smartscanner-android) library which simplifies the app intent call out process.
+
+## Running the demo app
+
+The Android demo app is available in this repository's `app` directory. Open this directory in Android Studio (version 4.1 and above) and the app can be built and run from there.
+
+## License
+
+[Apache-2.0 License](LICENSE)