NIAD-3435: Documentation improvements

common/README.md

@@ -1,25 +1,25 @@
 # Common
 
-This is a common module used by GP2GP Translator, GPC Api Facade and DB Connector modules.
+This is a common module used by GP2GP Translator, GPC API Facade and DB Connector modules.
 It holds any common util classes used by more than one module.
 
-## Util classes description
+## Utility classes description
 ### DateUtils
-Class for date-related methods.
-- `getCurrentOffsetDateTime()` method returns current UTC OffsetDateTime.
+Utility class for date-related methods.
+- `getCurrentOffsetDateTime()` method returns the current UTC `OffsetDateTime`.
 
 ### FhirParser
 This class offers methods for parsing and encoding FHIR resources.
-- `parseResource(String body, Class<T> fhirClass)` method parses String to given FHIR resource.
-- `encodeToJson(IBaseResource resource)` method parses FHIR resource to String.
+- `parseResource(String body, Class<T> fhirClass)` method parses a `String` to a given FHIR resource.
+- `encodeToJson(IBaseResource resource)` method encodes a FHIR resource to a `String`.
 
 ### ParametersUtils
-Here you can find method related to `Parameters` FHIR resource.
-- `getNhsNumberFromParameters(Parameters parameters)` method retrieves patient's NHS number value
- from Parameters resource.
+This class provides a method related to the `Parameters` FHIR resource.
+- `getNhsNumberFromParameters(Parameters parameters)` method retrieves the patient's NHS number value
+ from a `Parameters` resource.
 
 ### CreateParametersUtil
-This class keeps convenient methods for creating `Parameters` FHIR resource objects.
+This class provides convenient methods for creating `Parameters` FHIR resource objects.
 Meant to be used inside test classes.
 - `createValidParametersResource(String nhsNumberValue)` method returns a `Parameters` resource
- with given patient NHS number set.
+ with a given patient NHS number set.

db-connector/README.md

@@ -1,30 +1,30 @@
 # DB connector
 
-This is a common module, used by GP2GP Translator and GPC Api Facade.
+This is a common module, used by GP2GP Translator and GPC API Facade.
 It holds services needed for communication with the database.
 
 ## Migrations
-Migrations are implemented using Liquibase and need to be run manually before starting applications.
+Migrations are implemented using Liquibase and need to be run manually before starting the applications.
 
 To run the migrations, you need to specify the database URL and credentials of the database user
 that will be used to run the migrations. **This user needs to have permissions to create a database.**
 The first migration will try to connect to the default postgres database, to be able to create
-the patient_switching database used by the adapter. Then, the next set of the migrations
-will be executed on the patient_switching database.
+the `patient_switching` database used by the adaptor. Then, the next set of migrations
+will be executed on the `patient_switching` database.
 
-Set the following env variables:
-- PS_DB_OWNER_NAME
-- POSTGRES_PASSWORD
-- PS_DB_URL
+Set the following environment variables:
+- `PS_DB_OWNER_NAME`
+- `POSTGRES_PASSWORD`
+- `PS_DB_URL`
 
 To run the migrations use the following command:
 ```shell script
 ./gradlew update
 ```
-Changelog can be found under /changelog path.
+The changelog can be found under the `/changelog` path.
 
 ### How to add migrations
-To add a new migration, create a new xml file inside `/changelog/migration` directory.
+To add a new migration, create a new XML file inside the `/changelog/migration` directory.
 All files from this directory are included in the `db.changelog-master.xml` file.
 
 ## How to run tests
@@ -43,8 +43,8 @@ All files from this directory are included in the `db.changelog-master.xml` file
 
 ## Troubleshooting
 
-### gradle-wrapper.jar doesn't exist
+### `gradle-wrapper.jar` doesn't exist
 
-If gradle-wrapper.jar doesn't exist run in terminal:
-* Install Gradle (MacOS) `brew install gradle`
-* Update gradle `gradle wrapper`
+If `gradle-wrapper.jar` doesn't exist, run in terminal:
+* Install Gradle (macOS): `brew install gradle`
+* Update Gradle: `gradle wrapper`

gp2gp-translator/README.md

@@ -1,6 +1,6 @@
 # GP2GP Translator
 
-GP2GP Translator - new system that is the heart of the PSS Adaptor.
+GP2GP Translator - a new system that is the heart of the PSS Adaptor.
 It is responsible for GPC ↔︎ GP2GP translations, assembly of binary document data,
 communication with the incumbent system via MHS Adaptor and data cleanup.
 
@@ -20,26 +20,26 @@ communication with the incumbent system via MHS Adaptor and data cleanup.
 
 ### How to run integration tests:
 
-Integration tests require running database and queue.
-Make sure GP2GP Translator application is off, because if it's not, it will steal the message from the `inbound` queue
-before the application started by tests have a chance to grab it.
+Integration tests require a running database and queue.
+Make sure the GP2GP Translator application is off, because if it's not, it will steal the message from the `inbound` queue
+before the application started by the tests has a chance to grab it.
 
-Running tests form the terminal:
+Running tests from the terminal:
 ```shell script
 ./gradlew integrationTest
 ```
 
 You can also run tests from IntelliJ, just remember to set the database password
-inside the `gp2gp-translator/src/integrationTest/resources/application.yml` file (or set GP2GP_TRANSLATOR_USER_DB_PASSWORD variable).
+inside the `gp2gp-translator/src/integrationTest/resources/application.yml` file (or set the `GP2GP_TRANSLATOR_USER_DB_PASSWORD` variable).
 
-If your get lots of integration tests failures within the fixtures you can set the `BaseEhrHandler.OVERWRITE_EXPECTED_JSON`
+If you get lots of integration test failures within the fixtures, you can set the `BaseEhrHandler.OVERWRITE_EXPECTED_JSON`
 to `true` to regenerate them.
 Once regenerated, review the changes made using `git diff` or similar.
 
 ## Troubleshooting
 
-### gradle-wrapper.jar doesn't exist
+### `gradle-wrapper.jar` doesn't exist
 
-If gradle-wrapper.jar doesn't exist run in terminal:
-* Install Gradle (MacOS) `brew install gradle`
-* Update gradle `gradle wrapper`
+If `gradle-wrapper.jar` doesn't exist, run in terminal:
+* Install Gradle (macOS): `brew install gradle`
+* Update Gradle: `gradle wrapper`

gpc-api-facade/README.md

@@ -5,61 +5,83 @@ It enables NME to request and fetch patient data in the FHIR format.
 This facade only serves light tasks, delegating all the work to the async GP2GP Translator component.
 
 ## Enabling TLS
-To turn on the TLS MA, set SSL_ENABLED env variable to true. Also, you'll need to create a keystore and a truststore
+To turn on TLS Mutual Authentication (MA), set the `SSL_ENABLED` environment variable to `true`. You will also need to create a keystore and a truststore
 and set paths to them along with required passwords in those variables:
-- KEY_STORE: path to the keystore
-- KEY_STORE_PASSWORD: keystore password
-- KEY_PASSWORD: server private key password
-- TRUST_STORE: path to the truststore
-- TRUST_STORE_PASSWORD: truststore password
-
-To allow docker to fetch the keystore and truststore, you need to bind a directory containing them.
-You can achieve this by adding these lines to gpc_facade service in docker-compose.yml, below the `networks` part:
+- `KEY_STORE`: path to the keystore
+- `KEY_STORE_PASSWORD`: keystore password
+- `KEY_PASSWORD`: server private key password
+- `TRUST_STORE`: path to the truststore
+- `TRUST_STORE_PASSWORD`: truststore password
+
+To allow Docker to fetch the keystore and truststore, you need to bind a directory containing them.
+You can achieve this by adding these lines to the `gpc_facade` service in `docker-compose.yml`, below the `networks` part:
 ```yml
 volumes:
   - type: bind
     source: /Users/someuser/certs #path on your machine
     target: /certs #path on the docker volume
 ```
 
-You also need to import server's private key to the keystore, and import trusted client's public certificates
-(or root CA cert) to the truststore. Below you can find the instruction on how to create the server and client certificates
+You also need to import the server's private key to the keystore, and import the trusted client's public certificates
+(or root CA certificate) to the truststore. Below you can find the instructions on how to create the server and client certificates
 and how to import them.
 
 ### Creation of certificates
 
 1. Create the Root CA:
-> openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
+```
+openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
+```
 
 2. Create the Server Private Key
-> openssl genrsa -out server_private.key 4096
+```
+openssl genrsa -out server_private.key 4096
+```
 
 3. Create the CSR with private key for Root CA
-> openssl req -new -key server_private.key -out server.csr -sha256
+```
+openssl req -new -key server_private.key -out server.csr -sha256
+```
 
 4. Create the Server Public Certificate
-> openssl x509 -req -in server.csr -CA ca.cer -CAkey ca.key -set_serial 100 -extensions server -days 1460 -outform PEM -out server_public.cer -sha256
+```
+openssl x509 -req -in server.csr -CA ca.cer -CAkey ca.key -set_serial 100 -extensions server -days 1460 -outform PEM -out server_public.cer -sha256
+```
 
-5. Create a PKCS12 cert for server (it's needed to import the private key to the keystore)
-> openssl pkcs12 -export -inkey server_private.key -in server_public.cer -out server_pkcs.p12
+5. Create a PKCS12 cert for the server (it's needed to import the private key to the keystore)
+```
+openssl pkcs12 -export -inkey server_private.key -in server_public.cer -out server_pkcs.p12
+```
 
 6. Create the client private key
-> openssl genrsa -out client_private.key 4096
+```
+openssl genrsa -out client_private.key 4096
+```
 
 7. Create the CSR with client private key
-> openssl req -new -key client_private.key -out client.csr
+```
+openssl req -new -key client_private.key -out client.csr
+```
 
 8. Create the client public certificate
-> openssl x509 -req -in client.csr -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client_public.cer
+```
+openssl x509 -req -in client.csr -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client_public.cer
+```
 
-8. Create a PKCS12 cert for client
-> openssl pkcs12 -export -inkey client_private.key -in client_public.cer -out client_pkcs.p12
+9. Create a PKCS12 cert for the client
+```
+openssl pkcs12 -export -inkey client_private.key -in client_public.cer -out client_pkcs.p12
+```
 
-9. Import the server private key (using pkcs) to the keystore (keystore will be created if it doesn't exist)
-> keytool -importkeystore -srckeystore server_pkcs.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS
+10. Import the server private key (using PKCS) to the keystore (keystore will be created if it doesn't exist)
+```
+keytool -importkeystore -srckeystore server_pkcs.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS
+```
 
-10. Import the public client certificate to the truststore (truststore will be created if it doesn't exist)
-> keytool -keystore truststore.jks -importcert -file client_public.cer -alias client
+11. Import the public client certificate to the truststore (truststore will be created if it doesn't exist)
+```
+keytool -keystore truststore.jks -importcert -file client_public.cer -alias client
+```
 
 ## How to run tests
 
@@ -76,18 +98,18 @@ and how to import them.
 ```
 
 ### How to run integration tests:
-*Integration tests require running database and queue.*
-Running tests form the terminal:
+*Integration tests require a running database and queue.*
+Running tests from the terminal:
 ```shell script
 ./gradlew integrationTest
 ```
 You can also run tests from IntelliJ, just remember to set the database password
-inside the `gpc-api-facade/src/integrationTest/resources/application.yml` file (or set GPC_FACADE_USER_DB_PASSWORD variable).
+inside the `gpc-api-facade/src/integrationTest/resources/application.yml` file (or set the `GPC_FACADE_USER_DB_PASSWORD` variable).
 
 ## Troubleshooting
 
-### gradle-wrapper.jar doesn't exist
+### `gradle-wrapper.jar` doesn't exist
 
-If gradle-wrapper.jar doesn't exist run in terminal:
-* Install Gradle (MacOS) `brew install gradle`
-* Update gradle `gradle wrapper`
+If `gradle-wrapper.jar` doesn't exist, run in terminal:
+* Install Gradle (macOS): `brew install gradle`
+* Update Gradle: `gradle wrapper`

schema/README.md

@@ -1,11 +1,11 @@
 # Schema module
 
-This module holds xsd schemas and java classes generated based on those schemas.
-Schema files can be found inside src/resources directory.
+This module holds XSD schemas and Java classes generated based on those schemas.
+Schema files can be found inside the `src/resources` directory.
 
-## Generating java classes
+## Generating Java classes
 
-#### NOTE: Please use the newest version of the plugin: [gradle-xjc-plugin](https://github.com/unbroken-dome/gradle-xjc-plugin)
+### NOTE: Please use the newest version of the plugin: [gradle-xjc-plugin](https://github.com/unbroken-dome/gradle-xjc-plugin)
 
 
 1. Add `org.unbroken-dome.xjc` plugin in build.gradle:
@@ -21,23 +21,23 @@ Schema files can be found inside src/resources directory.
         srcDirName = 'resources/schema'
    }
    ```
-3. After reloading gradle, `xjcGenerate` gradle task should be present under
-   'code generation' category. Execute this task, it will generate java classes
+3. After reloading Gradle, the `xjcGenerate` Gradle task should be present under
+   the `code generation` category. Execute this task, it will generate Java classes
    based on schemas pointed in srcDirName property in build.gradle.
 
-4. Generated classes should be under `build/generated/sourced/xjc/java/main` path.
-   Copy them to `src/main/java` directory. Modify generated classes as needed.
-   Execute gradle `clean` task and remove changes added to build.gradle file.
+4. Generated classes should be under `build/generated/sources/xjc/java/main` path.
+   Copy them to `src/main/java` directory. Modify the generated classes as needed.
+   Execute the Gradle `clean` task and remove the changes added to the `build.gradle` file.
 
 ## Generating individual JAXB elements for testing
 
-When writing unit tests, you may be required to unmarshall code elements that haven't been pre-generated. The error you will see if this is the case will follow the general pattern of: 
+When writing unit tests, you may be required to unmarshal XML elements that haven't been pre-generated. The error you will see if this is the case will follow the general pattern of: 
 
 ```
 unexpected element (uri:"", local:"YOUR_ELEMENT"). Expected elements are <{urn:hl7-org:v3}PARENT_ELEMENT>
 ```
 
-This will require you add these elements directly to the `ObjectFactory.java` class independently.
+This will require you to add these elements directly to the `ObjectFactory.java` class independently.
 
 1. In `ObjectFactory.java`, register your element's QNAME in the custom made QNAME area.
 ```
@@ -55,7 +55,7 @@ This will require you add these elements directly to the `ObjectFactory.java` cl
 
 ## Manually modified classes
 
-Please make sure you don't override the following classes with the generated ones. They had to be manually changed to allow correct unmarshalling xml files to java objects:
+Please make sure you don't overwrite the following classes with the generated ones. They had to be manually changed to allow correct unmarshalling of XML files to Java objects:
 - EN.java 
 - RCMRMT030101UK04Place.java
 - IVLTS.java
@@ -99,16 +99,13 @@ Please make sure you don't override the following classes with the generated one
 - RCMRMT030101UK04Prescribe.java
 - RCMRMT030101UK04SupplyAnnotation.java
 - RCMRMT030101UK04Predecessor.java
-- TS.java
-- RCMRMT030101UK04NarrativeStatement.java
 - RCMRMT030101UK04InterpretationRange.java
 - RCCTMT120101UK01Device.java
-- RCMRMT030101UK04InterpretationRange.java
 - RCMRMT030101UK04SpecimenMaterial.java
 
 Removed files:
 - ST.java
 
 New file:
-- ValueAdapter.java - this is custom adapter helping with unmarshalling value element,
-  which can be of few different types
+- ValueAdapter.java - this is a custom adapter helping with unmarshalling the value element,
+  which can be of a few different types

smoke-tests/README.md

@@ -1,25 +1,25 @@
 # Smoke Tests
 
-## Running the smoke test
+## Running the smoke tests
 
 1. Make sure the environment is set up
-2. Ensure you are in the `smoketests` directory
-3. Run `.\run-smoke-tests.sh <path to your vars.sh script>`, where the parameter is the location of your configuration shell script.
+2. Ensure you are in the `smoke-tests` directory
+3. Run `./run-smoke-tests.sh <path to your vars.sh script>`, where the parameter is the location of your configuration shell script.
 
-#### Troubleshooting on M1 mac
+### Troubleshooting on M1 Mac
 
 Issue: `zsh: permission denied: ./run-smoke-tests.sh`
 
-Resolution: to give smoke tests script the permission to run - in your terminal run `chmod +x run-smoke-tests.sh`
+Resolution: To give the smoke tests script the permission to run, in your terminal run `chmod +x run-smoke-tests.sh`
 
 ----
 
 Issue: `zsh: permission denied: ./gradlew`
 
-Resolution: to give gradlew the permission to run - in your terminal run `chmod +x gradlew`
+Resolution: To give `gradlew` the permission to run, in your terminal run `chmod +x gradlew`
 
 ----
 
 Issue: `Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain`
 
-Resolution: ensure gradle is installed and the right version within the smoketest directory - run `brew install gradle`
+Resolution: Ensure Gradle is installed and the correct version is present within the `smoke-tests` directory. Run `brew install gradle`