fix review

docs/concept/persistence-storage.md

@@ -17,77 +17,173 @@ The most common IO mode is Synchronous IO, but it has a relatively low throughpu
 ## Directory
 ### Create
 Create the specified directory and return the file descriptor, the error will happen if the directory already exists.
-The following is the pseudocode that calls the API in the go style.
-`CreateDirectory(name String, permission int) (int, error)`
+The following is the pseudocode that calls the API in the go style.、
+
+param:
+
+name: The name of the directory.
+
+permisson: Permission you want to set. BanyanDB provides three modes: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`CreateDirectory(name String, permission Mode) (error)`
 
 ### Open
 Open the directory and return an error if the file descriptor does not exist.
 The following is the pseudocode that calls the API in the go style.
-`fd.OpenDirectory() (error)`
+
+param:
+
+name: The name of the directory.
+
+return: Directory pointer, you can use it for various operations.
+
+`OpenDirectory(name String) (*Dir, error)`
 
 ### Delete
 Delete the directory and all files and return an error if the directory does not exist or the directory not reading or writing.
 The following is the pseudocode that calls the API in the go style.
-`fd.DeleteDirectory() (error)`
+
+`Dir.DeleteDirectory() (error)`
 
 ### Rename
 Rename the directory and return an error if the directory already exists.
 The following is the pseudocode that calls the API in the go style.
-`fd.RenameDirectory(newName String) (error)`
 
-### Get Children
+param:
+
+name: The name of the directory.
+
+`Dir.RenameDirectory(newName String) (error)`
+
+### Read
 Get all lists of files or children's directories in the directory and an error if the directory does not exist.
 The following is the pseudocode that calls the API in the go style.
-`fd.ReadDirectory() (FileList, error)`
+
+return: List of files belonging to the directory.
+
+`Dir.ReadDirectory() (FileList, error)`
 
 ### Permission
 When creating a file, the default owner is the user who created the directory. The owner can specify read and write permissions of the directory. If not specified, the default is read and write permissions, which include permissions for all files in the directory.
 The following is the pseudocode that calls the API in the go style.
-`fd.SetDirectoryPermission(permission int) (error)`
+
+param:
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`Dir.SetDirectoryPermission(permission Mode) (error)`
 
 ## File
 ### Create
 Create the specified file and return the file descriptor, the error will happen if the file already exists.
 The following is the pseudocode that calls the API in the go style.
-`CreateFile(name String, permission int) (int, error)`
+
+param:
+
+name: The name of the file.
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`CreateFile(name String, permission Mode) (error)`
 
 ### Open
 Open the file and return an error if the file descriptor does not exist.
 The following is the pseudocode that calls the API in the go style.
-`fd.OpenFile() (error)`
+
+param:
+
+name: The name of the file.
+
+return: File pointer, you can use it for various operations.
+
+`OpenFile(name String) (*File, error)`
 
 ### Write
 BanyanDB provides two methods for writing files.
 Append mode, which adds new data to the end of a file. This mode is typically used for WAL.
-Flush mode, which flushes all data to one file. It will return an error when writing a directory, the file does not exist or there is not enough space, and the incomplete file will be discarded.
+Flush mode, which flushes all data to one file. It will return an error when writing a directory, the file does not exist or there is not enough space, and the incomplete file will be discarded. The flush operation is atomic, which means the file won't be created if an error happens during the flush process.
 The following is the pseudocode that calls the API in the go style.
-For append mode: `fd.AppendWriteFile(data []byte) (error)`
-For flush mode:  `FlushWriteFile(data []byte, permission int) (int, error)`
+
+For append mode:
+
+param:
+
+buffer: The data append to the file.
+
+`File.AppendWriteFile(buffer []byte) (error)`
+
+For flush mode:
+
+param:
+
+buffer: The data append to the file.
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+return: File pointer, you can use it for various operations.
+
+`FlushWriteFile(buffer []byte, permission Mode) (*File, error)`
 
 ### Delete
-BanyanDB provides a batch-deleting operation, which can delete several files at once. it will return an error if the directory does not exist or the file not reading or writing.
+BanyanDB provides the deleting operation, which can delete a file at once. it will return an error if the directory does not exist or the file not reading or writing.
+
 The following is the pseudocode that calls the API in the go style.
-`DeleteFile(fds List) (error)`
+
+`File.DeleteFile() (error)`
 
 ### Read
 For reading operation, two read methods are provided:
 Reading a specified location of data, which relies on a specified offset and a buffer.
 Read the entire file, BanyanDB provides stream reading, which can use when the file is too large, the size gets each time can be set when using stream reading.
 If entering incorrect parameters such as incorrect offset or non-existent file, it will return an error.
 The following is the pseudocode that calls the API in the go style.
-`fd.ReadFile(offset int, data []byte) (error)`
+
+For reading specified location of data:
+
+param:
+
+offset: Read begin location of the file.
+
+buffer: The read length is the same as the buffer length.
+
+`File.ReadFile(offset int, buffer []byte) (error)`
+
+For stream reading:
+
+param:
+
+offset: Read begin location of the file.
+
+buffer: Every read length in the stream is the same as the buffer length.
+
+return: A Iterator, the size of each iteration is the length of the buffer.
+
+`File.StreamReadFile(offset int, buffer []byte) (*iter, error)`
 
 ### Rename
 Rename the file and return an error if the directory exists in this directory.
 The following is the pseudocode that calls the API in the go style.
-`fd.RenameFile(newName String) (error)`
+
+param:
+
+newName: The new name of the file.
+
+`File.RenameFile(newName String) (error)`
 
 ### Get size
-Get the file size and return an error if the file does not exist. The unit of file size is Byte.
+Get the file written data's size and return an error if the file does not exist. The unit of file size is Byte.
 The following is the pseudocode that calls the API in the go style.
-`fd.GetFileSize() (int, error)`
+
+return: the file written data's size.
+
+`File.GetFileSize() (int, error)`
 
 ### Permission
 When creating a file, the default owner is the user who created the file. The owner can specify the read and write permissions of the file. If not specified, the default is read and write permissions.
 The following is the pseudocode that calls the API in the go style.
-`fd.SetFilePermission(permission int) (error)`
+
+param:
+
+permisson: Permission you want to set. BanyanDB provides three mode: Read, Write, ReadAndWrite. you can use it as Mode.Read.
+
+`File.SetFilePermission(permission Mode) (error)`