Review API documentation in BI editor

ballerina/block_stream.bal

@@ -18,14 +18,13 @@ import ballerina/jballerina.java;
 # The read-only byte array that is used to read the byte content from the streams.
 public type Block readonly & byte[];
 
-# The `BlockStream` is used to initialize a stream of type `Block`. This `BlockStream` refers to the stream that is embedded to
-# the I/O byte channels.
+# A stream of `Block` objects that is used to read the byte content from the streams.
 public class BlockStream {
     private ReadableByteChannel readableByteChannel;
     private int blockSize;
     private boolean isClosed = false;
 
-    # Initialize a `BlockStream` using an `io:ReadableByteChannel`.
+    # Initializes a stream of `Block` objects.
     #
     # + readableByteChannel - The `io:ReadableByteChannel` that this block stream is referred to
     # + blockSize - The size of a block as an integer
@@ -34,9 +33,9 @@ public class BlockStream {
         self.blockSize = blockSize;
     }
 
-    # The next function reads and returns the next block of the related stream.
+    # Reads the next block of the stream.
     #
-    # + return - An `io:Block` when a block is avaliable in the stream or returns `()` when the stream reaches the end
+    # + return - An `io:Block` when a block is available in the stream or returns `()` when the stream reaches the end
     public isolated function next() returns record {|Block value;|}|Error? {
         byte[]|Error block = readBlock(self.readableByteChannel, self.blockSize);
         if block is byte[] {
@@ -49,8 +48,8 @@ public class BlockStream {
         }
     }
 
-    # Closes the stream. The primary usage of this function is to close the stream without reaching the end
-    # If the stream reaches the end, the `BlockStream.next()` will automatically close the stream.
+    # Closes the stream manually.
+    # If not invoked, the stream closes automatically upon reaching end-of-stream.
     #
     # + return - `()` when the closing was successful or an `io:Error`
     public isolated function close() returns Error? {

ballerina/constants.bal

@@ -14,7 +14,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-# The format, which will be used to represent the CSV.
+# Specifies the format used to represent CSV data.
 #
 # DEFAULT - The default value is the format specified by the CSVChannel. Precedence will be given to the field
 # separator and record separator.

ballerina/csv_stream.bal

@@ -15,22 +15,21 @@
 // under the License.
 import ballerina/jballerina.java;
 
-# The `io:CSVStream` is used to initialize a stream of type CSV records. This `io:CSVStream` refers to the stream
-# that is embedded to the I/O record channels.
+# A stream of CSV records that is used to read the CSV content from the streams.
 public class CSVStream {
     private ReadableTextRecordChannel readableTextRecordChannel;
     private boolean isClosed = false;
 
-    # Initialize a `CSVStream` using an `io:ReadableTextRecordChannel`.
+    # Initializes a stream of CSV records.
     #
     # + readableTextRecordChannel - The `io:ReadableTextRecordChannel` that this CSV stream is referred to
     public isolated function init(ReadableTextRecordChannel readableTextRecordChannel) {
         self.readableTextRecordChannel = readableTextRecordChannel;
     }
 
-    # The next function reads and returns the next CSV record of the related stream.
+    # Reads the next CSV record of the stream.
     #
-    # + return - A CSV record as a string array when a record is avaliable in the stream or
+    # + return - A CSV record as a string array when a record is available in the stream or
     # `()` when the stream reaches the end
     public isolated function next() returns record {|string[] value;|}|Error? {
         var recordValue = readRecord(self.readableTextRecordChannel);
@@ -45,8 +44,8 @@ public class CSVStream {
         }
     }
 
-    # Close the stream. The primary usage of this function is to close the stream without reaching the end.
-    # If the stream reaches the end, the `CSVStream.next()` will automatically close the stream.
+    # Closes the stream manually.
+    # If not invoked, the stream closes automatically upon reaching end-of-stream.
     #
     # + return - `()` when the closing was successful or an `io:Error`
     public isolated function close() returns Error? {

ballerina/file_byte_io.bal

@@ -14,52 +14,52 @@
 // specific language governing permissions and limitations
 // under the License.
 
-# Read the entire file content as a byte array.
+# Reads the entire file content as a byte array.
 # ```ballerina
 # byte[]|io:Error content = io:fileReadBytes("./resources/myfile.txt");
 # ```
-# + path - The path of the file
+# + path - The file path
 # + return - A read-only byte array or an `io:Error`
 public isolated function fileReadBytes(string path) returns readonly & byte[]|Error {
     return channelReadBytes(check openReadableFile(path));
 }
 
-# Read the entire file content as a stream of blocks.
+# Reads the entire file content as a stream of blocks.
 # ```ballerina
 # stream<io:Block, io:Error?>|io:Error content = io:fileReadBlocksAsStream("./resources/myfile.txt", 1000);
 # ```
-# + path - The path of the file
+# + path - The file path
 # + blockSize - An optional size of the byte block. The default size is 4KB
 # + return - A byte block stream or an `io:Error`
 public isolated function fileReadBlocksAsStream(string path, int blockSize = 4096) returns stream<Block, Error?>|
 Error {
     return channelReadBlocksAsStream(check openReadableFile(path), blockSize);
 }
 
-# Write a set of bytes to a file.
+# Writes a set of bytes to a file.
 # ```ballerina
 # byte[] content = [60, 78, 39, 28];
 # io:Error? result = io:fileWriteBytes("./resources/myfile.txt", content);
 # ```
-# + path - The path of the file
+# + path - The file path
 # + content - Byte content to write
-# + option - To indicate whether to overwrite or append the given content
-# + return - An `io:Error` or else `()`
+# + option - Indicate whether to overwrite or append the given content
+# + return - An `io:Error` if the write operation fails, or ()
 public isolated function fileWriteBytes(string path, byte[] content, FileWriteOption option = OVERWRITE) returns
 Error? {
     return channelWriteBytes(check openWritableFile(path, option), content);
 }
 
-# Write a byte stream to a file.
+# Writes a byte stream to a file.
 # ```ballerina
 # byte[] content = [[60, 78, 39, 28]];
 # stream<byte[], io:Error?> byteStream = content.toStream();
 # io:Error? result = io:fileWriteBlocksFromStream("./resources/myfile.txt", byteStream);
 # ```
-# + path - The path of the file
+# + path - The file path
 # + byteStream - Byte stream to write
-# + option - To indicate whether to overwrite or append the given content
-# + return - An `io:Error` or else `()`
+# + option - Indicate whether to overwrite or append the given content
+# + return - An `io:Error` if the write operation fails, or ()
 public isolated function fileWriteBlocksFromStream(string path, stream<byte[], Error?> byteStream,
                                                     FileWriteOption option = OVERWRITE) returns Error? {
     return channelWriteBlocksFromStream(check openWritableFile(path, option), byteStream);

ballerina/file_csv_io.bal

@@ -15,7 +15,7 @@
 // under the License.
 import ballerina/jballerina.java;
 
-# Read file content as a CSV.
+# Reads file content as a CSV.
 # When the expected data type is record[], the first entry of the csv file should contain matching headers.
 # ```ballerina
 # string[][]|io:Error content = io:fileReadCsv("./resources/myfile.csv");
@@ -30,9 +30,8 @@ public isolated function fileReadCsv(string path, int skipHeaders = 0, typedesc<
     'class: "io.ballerina.stdlib.io.nativeimpl.CsvChannelUtils"
 } external;
 
-# Read file content as a CSV.
-# When the expected data type is stream<record, io:Error?>,
-# the first entry of the csv file should contain matching headers.
+# Reads file content as a CSV.
+# When the expected data type is stream<record, io:Error?>, the first entry of the csv file should contain matching headers.
 # ```ballerina
 # stream<string[]|io:Error content = io:fileReadCsvAsStream("./resources/myfile.csv");
 # stream<record{}, io:Error?>|io:Error content = io:fileReadCsvAsStream("./resources/myfile.csv");
@@ -45,9 +44,9 @@ public isolated function fileReadCsvAsStream(string path, typedesc<string[]|map<
     'class: "io.ballerina.stdlib.io.nativeimpl.CsvChannelUtils"
 } external;
 
-# Write CSV content to a file.
-# When the input is a record[] type in `OVERWRITE`,  headers will be written to the CSV file by default.
-# For `APPEND`, order of the existing csv file is inferred using the headers and used as the order.
+# Writes CSV content to a file.
+# When the input is a record[] type in `OVERWRITE`, headers will be written to the CSV file.
+# For `APPEND`, order of the existing csv file is inferred using the headers.
 # ```ballerina
 # type Coord record {int x;int y;};
 # Coord[] contentRecord = [{x: 1,y: 2},{x: 1,y: 2}]
@@ -56,17 +55,17 @@ public isolated function fileReadCsvAsStream(string path, typedesc<string[]|map<
 # io:Error? resultRecord = io:fileWriteCsv("./resources/myfileRecord.csv", contentRecord);
 # ```
 # + path - The CSV file path
-# + content - CSV content as an array of string arrays or a array of Ballerina records
-# + option - To indicate whether to overwrite or append the given content
+# + content - CSV content as a two-dimensional string array or a Ballerina records array
+# + option - Indicate whether to overwrite or append the given content
 # + return - `()` when the writing was successful or an `io:Error`
 public isolated function fileWriteCsv(string path, string[][]|map<anydata>[] content, FileWriteOption option = OVERWRITE) returns
 Error? {
     return channelWriteCsv(path, option, content);
 }
 
-# Write CSV record stream to a file.
-# When the input is a `stream<record, io:Error?>` in `OVERWRITE`,  headers will be written to the CSV file by default.
-# For `APPEND`, order of the existing csv file is inferred using the headers and used as the order.
+# Writes CSV record stream to a file.
+# When the input is a `stream<record, io:Error?>` in `OVERWRITE`, headers will be written to the CSV file.
+# For `APPEND`, order of the existing csv file is inferred using the headers.
 # ```ballerina
 # type Coord record {int x;int y;};
 # Coord[] contentRecord = [{x: 1,y: 2},{x: 1,y: 2}]
@@ -78,7 +77,7 @@ Error? {
 # ```
 # + path - The CSV file path
 # + content - A CSV record stream to be written
-# + option - To indicate whether to overwrite or append the given content
+# + option - Indicate whether to overwrite or append the given content
 # + return - `()` when the writing was successful or an `io:Error`
 public isolated function fileWriteCsvFromStream(string path, stream<string[]|map<anydata>, Error?> content,
         FileWriteOption option = OVERWRITE) returns Error? {

ballerina/file_string_io.bal

@@ -19,7 +19,7 @@
 # ```ballerina
 # string|io:Error content = io:fileReadString("./resources/myfile.txt");
 # ```
-# + path - The path of the file
+# + path - The file path
 # + return - The entire file content as a string or an `io:Error`
 public isolated function fileReadString(string path) returns string|Error {
     return channelReadString(check openReadableFile(path));
@@ -30,8 +30,8 @@ public isolated function fileReadString(string path) returns string|Error {
 # ```ballerina
 # string[]|io:Error content = io:fileReadLines("./resources/myfile.txt");
 # ```
-# + path - The path of the file
-# + return - The file as list of lines or an `io:Error`
+# + path - The file path
+# + return - The file content as a string array or an `io:Error`
 public isolated function fileReadLines(string path) returns string[]|Error {
     return channelReadLines(check openReadableFile(path));
 }
@@ -41,7 +41,7 @@ public isolated function fileReadLines(string path) returns string[]|Error {
 # ```ballerina
 # stream<string, io:Error?>|io:Error content = io:fileReadLinesAsStream("./resources/myfile.txt");
 # ```
-# + path - The path of the file
+# + path - The file path
 # + return - The file content as a stream of strings or an `io:Error`
 public isolated function fileReadLinesAsStream(string path) returns stream<string, Error?>|Error {
     return channelReadLinesAsStream(check openReadableFile(path));
@@ -51,7 +51,7 @@ public isolated function fileReadLinesAsStream(string path) returns stream<strin
 # ```ballerina
 # json|io:Error content = io:fileReadJson("./resources/myfile.json");
 # ```
-# + path - The path of the JSON file
+# + path - The JSON file path
 # + return - The file content as a JSON object or an `io:Error`
 public isolated function fileReadJson(string path) returns json|Error {
     return channelReadJson(check openReadableFile(path));
@@ -61,75 +61,75 @@ public isolated function fileReadJson(string path) returns json|Error {
 # ```ballerina
 # xml|io:Error content = io:fileReadXml("./resources/myfile.xml");
 # ```
-# + path - The path of the XML file
+# + path - The XML file path
 # + return - The file content as an XML or an `io:Error`
 public isolated function fileReadXml(string path) returns xml|Error {
     return channelReadXml(check openReadableFile(path));
 }
 
-# Write a string content to a file.
+# Writes a string content to a file.
 # ```ballerina
 # string content = "Hello Universe..!!";
 # io:Error? result = io:fileWriteString("./resources/myfile.txt", content);
 # ```
-# + path - The path of the file
+# + path - The file path
 # + content - String content to write
-# + option - To indicate whether to overwrite or append the given content
+# + option - Indicate whether to overwrite or append the given content
 # + return - `()` when the writing was successful or an `io:Error`
 public isolated function fileWriteString(string path, string content, FileWriteOption option = OVERWRITE) returns
 Error? {
     return channelWriteString(check openWritableFile(path, option), content);
 }
 
-# Write an array of lines to a file.
+# Writes an array of lines to a file.
 # During the writing operation, a newline character `\n` will be added after each line.
 # ```ballerina
 # string[] content = ["Hello Universe..!!", "How are you?"];
 # io:Error? result = io:fileWriteLines("./resources/myfile.txt", content);
 # ```
-# + path - The path of the file
+# + path - The file path
 # + content - An array of string lines to write
-# + option - To indicate whether to overwrite or append the given content
+# + option - Indicate whether to overwrite or append the given content
 # + return - `()` when the writing was successful or an `io:Error`
 public isolated function fileWriteLines(string path, string[] content, FileWriteOption option = OVERWRITE) returns
 Error? {
     return channelWriteLines(check openWritableFile(path, option), content);
 }
 
-# Write stream of lines to a file.
+# Writes a stream of lines to a file.
 # During the writing operation, a newline character `\n` will be added after each line.
 # ```ballerina
 # string content = ["Hello Universe..!!", "How are you?"];
 # stream<string, io:Error?> lineStream = content.toStream();
 # io:Error? result = io:fileWriteLinesFromStream("./resources/myfile.txt", lineStream);
 # ```
-# + path - The path of the file
+# + path - The file path
 # + lineStream - A stream of lines to write
-# + option - To indicate whether to overwrite or append the given content
+# + option - Indicate whether to overwrite or append the given content
 # + return - `()` when the writing was successful or an `io:Error`
 public isolated function fileWriteLinesFromStream(string path, stream<string, Error?> lineStream,
                                                 FileWriteOption option = OVERWRITE) returns Error? {
     return channelWriteLinesFromStream(check openWritableFile(path, option), lineStream);
 }
 
-# Write a JSON to a file.
+# Writes a JSON to a file.
 # ```ballerina
 # json content = {"name": "Anne", "age": 30};
 # io:Error? result = io:fileWriteJson("./resources/myfile.json", content);
 # ```
-# + path - The path of the JSON file
+# + path - The JSON file path
 # + content - JSON content to write
 # + return - `()` when the writing was successful or an `io:Error`
 public isolated function fileWriteJson(string path, json content) returns Error? {
     return channelWriteJson(check openWritableFile(path), content);
 }
 
-# Write XML content to a file.
+# Writes XML content to a file.
 # ```ballerina
 # xml content = xml `<book>The Lost World</book>`;
 # io:Error? result = io:fileWriteXml("./resources/myfile.xml", content);
 # ```
-# + path - The path of the XML file
+# + path - The XML file path
 # + content - XML content to write
 # + xmlOptions - XML writing options (XML entity type and DOCTYPE)
 # + fileWriteOption - File write option (`OVERWRITE` and `APPEND` are the possible values and the default value is `OVERWRITE`)

ballerina/line_stream.bal

@@ -15,22 +15,21 @@
 // under the License.
 import ballerina/jballerina.java;
 
-# The `io:LineStream` is used to initialize a stream of the type strings(lines). This `io:LineStream` refers to the
-# stream that is embedded to the I/O character channels.
+# A stream of strings(lines) that is used to read the character content from the streams.
 public class LineStream {
     private ReadableCharacterChannel readableCharacterChannel;
     private boolean isClosed = false;
 
-    # Initialize an `io:LineStream` using an `io:ReadableCharacterChannel`.
+    # Initializes A stream of strings(lines).
     #
     # + readableCharacterChannel - The `io:ReadableCharacterChannel` that the line stream is referred to
     public isolated function init(ReadableCharacterChannel readableCharacterChannel) {
         self.readableCharacterChannel = readableCharacterChannel;
     }
 
-    # The next function reads and returns the next line of the related stream.
+    # Reads the next line of the stream.
     #
-    # + return - A line as a string when a line is avaliable in the stream or returns `()` when the stream reaches the end
+    # + return - A line as a string when a line is available in the stream or returns `()` when the stream reaches the end
     public isolated function next() returns record {|string value;|}|Error? {
         var line = readLine(self.readableCharacterChannel);
         if line is string {
@@ -44,8 +43,8 @@ public class LineStream {
         }
     }
 
-    # Closes the stream. The primary usage of this function is to close the stream without reaching the end
-    # If the stream reaches the end, the `LineStream.next()` will automatically close the stream.
+    # Closes the stream manually.
+    # If not invoked, the stream closes automatically upon reaching end-of-stream.
     #
     # + return - `()` when the closing was successful or an `io:Error`
     public isolated function close() returns Error? {