Refactor spec

docs/spec/spec.md

@@ -3,7 +3,7 @@
 _Owners_: @shafreenAnfar @MadhukaHarith92  
 _Reviewers_: @shafreenAnfar  
 _Created_: 2023/06/07  
-_Updated_: 2023/06/07  
+_Updated_: 2023/08/14  
 _Edition_: Swan Lake
 
 ## Introduction
@@ -18,22 +18,34 @@ The conforming implementation of the specification is released and included in t
 ## Contents
 
 1. [Overview](#1-overview)
-2. [Compatibility](#2-compatibility)
-3. [Usage Example](#3-usage-example)
+2. [Components](#2-components)
+   * 2.1 [Client](#21-client)
+       * 2.1.1 [Initializing the Client](#211-initializing-the-client)
+       * 2.1.2 [SendReceive](#211-sendreceive)
+       * 2.1.3 [SendOnly](#213-sendonly)
 
 ## 1. Overview
 This specification elaborates on the functions available in the Soap library.
 
 The soap module abstracts out the details of the creation of a SOAP envelope, headers, and the body in a SOAP message.
 
-## 2. Compatibility
+## 2. Components
+This section describes the components of the Ballerina SOAP package. To use the Ballerina SOAP package, a user must import the Ballerina SOAP package first.
+```ballerina
+import ballerina/soap;
+```
+
+### 2.1 Client
+
+The SOAP client can be used to connect to a SOAP service and retrieve data. 
+
+#### 2.1.1 Initializing the Client
 
-|                          |      Versions      |
-|:------------------------:|:------------------:|
-| Ballerina Language       | 2201.7.0           |
-| SOAP Version             | 0.1                |
+The soap:Client init method requires a valid URL and optional configuration to initialize the client.
 
-## 3. Usage Example
+#### 2.1.2 SendReceive
+
+The `sendReceive` function sends SOAP request and expects a response.
 
 ```ballerina
 import ballerina/io;
@@ -54,44 +66,24 @@ public function main () returns error? {
 }
 ```
 
-Follow the steps below to run this example.
-
-1. Save the example in a Ballerina file (e.g., `soapExample.bal`).
-2. Execute the `ballerina run soapExample.bal` command to run the file.
-   You will get a response similar to the following.
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<soap:Body xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
-   <CheckPhoneNumberResponse xmlns="http://ws.cdyne.com/PhoneVerify/query">
-      <CheckPhoneNumberResult>
-         <Company>Toll Free</Company>
-         <Valid>true</Valid>
-         <Use>Assigned to a code holder for normal use.</Use>
-         <State>TF</State>
-         <RC />
-         <OCN />
-         <OriginalNumber>18006785432</OriginalNumber>
-         <CleanNumber>8006785432</CleanNumber>
-         <SwitchName />
-         <SwitchType />
-         <Country>United States</Country>
-         <CLLI />
-         <PrefixType>Landline</PrefixType>
-         <LATA />
-         <sms>Landline</sms>
-         <Email />
-         <AssignDate>Unknown</AssignDate>
-         <TelecomCity />
-         <TelecomCounty />
-         <TelecomState>TF</TelecomState>
-         <TelecomZip />
-         <TimeZone />
-         <Lat />
-         <Long />
-         <Wireless>false</Wireless>
-         <LRN />
-      </CheckPhoneNumberResult>
-   </CheckPhoneNumberResponse>
-</soap:Body>
+#### 2.1.3 SendOnly
+
+The `sendOnly` function fires and forgets requests. It sends the request without the possibility of any response from the service (even an error).
+
+```ballerina
+import ballerina/io;
+import ballerina/soap;
+import ballerina/mime;
+  
+public function main () returns error? {
+
+    soap:Client soapClient = check new("http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl");
+
+    xml body = xml `<quer:CheckPhoneNumber xmlns:quer="http://ws.cdyne.com/PhoneVerify/query"> 
+         <quer:PhoneNumber>18006785432</quer:PhoneNumber>
+         <quer:LicenseKey>0</quer:LicenseKey>
+      </quer:CheckPhoneNumber>`;
+
+    _ = check soapClient->sendOnly(body);
+}
 ```