Added more documentation

Project.toml

@@ -16,5 +16,5 @@ XRootD_jll = "5.6"
 julia = "1.6"
 
 [extras]
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -3,7 +3,7 @@
 
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https:///JuliaHEP.github.io/XRootD.jl/dev/)
 [![Build Status](https://github.com/JuliaHEP/XRootD.jl/workflows/CI/badge.svg)](https://github.com/JuliaHEP/XRootD.jl/actions)
-[![codecov](https://codecov.io/gh/JuliaHEP/XRootD.jl/graph/badge.svg?token=AS74WXOYT6)](https://codecov.io/gh/JuliaHEP/XRootD.jl)[![License](https://img.shields.io/badge/license-LGPL-blue.svg)](LICENSE)
+[[![License](https://img.shields.io/badge/license-LGPL-blue.svg)](LICENSE)
 
 ## Description
 

docs/src/api.md

@@ -2,24 +2,22 @@
 
 Documentation for `XRootD.jl` public interface.
 
-## Index - Types
+---
+
+## Index
 ```@index
 Pages   = ["api.md"]
 Modules = [XRootD, XRootD.XrdCl]
 Order   = [:type]
 ```
-## Index - Functions
 ```@index
 Pages   = ["api.md"]
-Modules = [XRootD, XRootD.XrdCl]
+Modules = [XRootD, XRootD.XrdCl, Base]
 Order   = [:function]
 ```
 
-## Modules
-```@autodocs
-Modules = [XRootD, XRootD.XrdCl]
-Order = [:module]
-```
+---
+
 ## Types
 This is the list of all types and functions defined for XRootD
 

docs/src/index.md

@@ -1,11 +1,11 @@
-# Julia binding for XRootD
+# Julia bindings for XRootD
 
 ## Description
 
 Julia bindings for the [XRootD](https://xrootd.slac.stanford.edu) high performance, scalable, and fault tolerant access to data repositories. It facilitates the interface with the XRootD client, by writing Julia code instead of having to write C++ code.
 This package is developed using the [CxxWrap.jl](https://github.com/JuliaInterop/CxxWrap.jl) package to wrap C++ types and functions to Julia. Wrapper C++ code is generated with the help of [WrapIt](https://github.com/grasph/wrapit) tool that uses of the clang library.
 
-The Julia interface has been inspired by the functionality provided by [pyxrootd](https://xrootd.slac.stanford.edu/doc/doxygen/5.6.4/python/), which provide a set of simple but pythonic bindings for XRootD.
+The Julia interface has been inspired by the functionality provided by [pyxrootd](https://xrootd.slac.stanford.edu/doc/doxygen/5.6.4/python/), which provide a set of simple but pythonic bindings for XRootD. In the case of Julia we have used the same function names if there was an equivalent in the `Base` module.
 
 ## Installation
 The XRootD.jl package does no require any special installation. Stable releases are registered into the Julia general registry, and therefore can be deployed with the standard `Pkg` Julia package manager.
@@ -62,12 +62,10 @@ close(f)
 st, _ = rm(fs, "/tmp/testfile.txt")
 ```
 
-## Roadmap
-There are a number of issues and problems still to be resolved. We keep track of them in this list:
-- Is is necessary to have the async interface? 
-
-
 ## Tests
 Unit tests can be run with `julia --project=. test/runtests.jl`
 
-## Examples
+## Roadmap
+There are a number of issues and problems still to be resolved. We keep track of them in this list:
+- Is is necessary to have the async interface?
+- Benchmark the performance of `XRootD` versus `xrootdgo`

src/File.jl

@@ -11,7 +11,13 @@ File() = File(XRootD.XrdCl!File(), 0, 0)
 """
     File(url::String, flags=0x0000, mode=0x0000)
 
-File crates a File object and opens it.
+Create a File object and to open it.
+# Arguments
+- `url::String`: the URL of the file.
+- `flags::Int`: the flags to open the file (examples: OpenFlags.Read, OpenFlags.Write, OpenFlags.Delete).
+- `mode::Int`: the mode to open the file (examples: Access.UR, Access.UW).
+# Returns
+- `File`: the File object (if the file is opened successfully) or `nothing`.
 """
 function File(url::String, flags=0x0000, mode=0x0000)
     file = XRootD.XrdCl!File()
@@ -29,6 +35,10 @@ end
     Base.isopen(f::File)
 
 Check if the file is open.
+# Arguments
+- `f::File`: the File object.
+# Returns
+- `Bool`: `true` if the file is open, `false` otherwise.
 """
 function Base.isopen(f::File)
     XRootD.IsOpen(f.file)
@@ -38,6 +48,15 @@ end
     Base.open(f::File, url::String, flags=0x0000, mode=0x0000)
 
 Open a file.
+# Arguments
+- `f::File`: the File object.
+- `url::String`: the URL of the file.
+- `flags::Int`: the flags to open the file (examples: OpenFlags.Read, OpenFlags.Write, OpenFlags.Delete).
+- `mode::Int`: the mode to open the file (examples: Access.UR, Access.UW).
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `nothing`
 """
 function Base.open(f::File, url::String, flags=0x0000, mode=0x0000)
     st = Open(f.file, url, flags, mode)
@@ -51,6 +70,12 @@ end
     Base.close(f::File)
 
 Close the file.
+# Arguments
+- `f::File`: the File object.
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `nothing`
 """
 function Base.close(f::File)
     st = Close(f.file)
@@ -63,6 +88,13 @@ end
     Base.stat(f::File, force::Bool=true)
 
 Stat the file.
+# Arguments
+- `f::File`: the File object.
+- `force::Bool`: force the stat operation.
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `StatInfo`: the stat information (or `nothing` if the operation failed).
 """
 function Base.stat(f::File, force::Bool=true)
     statinfo_p = Ref(CxxPtr{StatInfo}(C_NULL))
@@ -80,6 +112,10 @@ end
     Base.eof(f::File)
 
 Check if the file is at the end.
+# Arguments
+- `f::File`: the File object.
+# Returns
+- `Bool`: `true` if the file is at the end, `false` otherwise.
 """
 function Base.eof(f::File)
     return f.currentOffset >= f.filesize
@@ -89,6 +125,13 @@ end
     Base.truncate(f::File, size::Int64)
 
 Truncate the file.
+# Arguments
+- `f::File`: the File object.
+- `size::Int64`: the size to truncate the file.
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `nothing`
 """
 function Base.truncate(f::File, size::Int64)
     st = Truncate(f.file, size)
@@ -99,6 +142,15 @@ end
     Base.write(f::File, data::Array{UInt8}, size, offset=0)
 
 Write data to the file.
+# Arguments
+- `f::File`: the File object.
+- `data::Array{UInt8}`: the data to write.
+- `size::Int`: the size of the data to be writen.
+- `offset::Int`: the offset to write the data.
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `nothing`
 """
 function Base.write(f::File, data::Array{UInt8}, size, offset=0)
     data_p = convert(Ptr{Nothing}, pointer(data))
@@ -111,6 +163,15 @@ Base.write(f::File, data::String, offset=0) = Base.write(f, Vector{UInt8}(data),
     Base.read(f::File, size, offset=0)
 
 Read data from the file.
+# Arguments
+- `f::File`: the File object.
+- `size::Int`: the size of the data to read.
+- `offset::Int`: the offset to read the data.
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `Array{UInt8}`: the data read (or `nothing` if the operation failed).
+
 """
 function Base.read(f::File, size, offset=0)
     buffer = Array{UInt8}(undef, size)
@@ -132,7 +193,16 @@ end
 """
     Base.readline(f::File, size=0, offset=0, chunk=0)
 
-readline reads a line from the file.
+read one line from the file until it finds a linefeed (\n) or reaches the end of the file.
+# Arguments
+- `f::File`: the File object.
+- `size::Int`: the maximum size of the line to read.
+- `offset::Int`: the offset in the file (0 indicates to continue reading from previous position).
+- `chunk::Int`: the size of the chunk to read (0 indicates 2MB).
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `String`: the line read (or `nothing` if the operation failed).
 """
 function Base.readline(f::File, size=0, offset=0, chunk=0)
     if offset == 0
@@ -170,6 +240,15 @@ end
     Base.readlines(f::File, size=0, offset=0, chunk=0)
 
 readlines reads lines from the file.
+# Arguments
+- `f::File`: the File object.
+- `size::Int`: the maximum size of the lines to read.
+- `offset::Int`: the offset in the file (0 indicates to continue reading from previous position).
+- `chunk::Int`: the size of the chunk to read (0 indicates 2MB).
+# Returns
+- `Tuple` of:
+    - `XRootDStatus`: the status of the operation.
+    - `Array{String}`: the lines read (or `nothing` if the operation failed).
 """
 function Base.readlines(f::File, size=0, offset=0, chunk=0)
     lines = String[]