update documentation

Author: abhinavmehndiratta

src/Context_Methods.jl

@@ -1,10 +1,24 @@
 import GraphBLASInterface:
         GrB_init, GrB_finalize
 
+"""
+    GrB_init(mode)
+
+`GrB_init` must called before any other GraphBLAS operation.
+`GrB_init` defines the mode that GraphBLAS will use: blocking or non-blocking.
+With blocking mode, all operations finish before returning to the user application.
+With non-blocking mode, operations can be left pending, and are computed only when needed.
+"""
 function GrB_init(mode::GrB_Mode)
     return GrB_Info(ccall(dlsym(graphblas_lib, "GrB_init"), Cint, (Cint, ), mode))
 end
 
+"""
+    GrB_finalize()
+
+`GrB_finalize` must be called as the last GraphBLAS operation.
+`GrB_finalize` does not call `GrB_wait`; any pending computations are abandoned.
+"""
 function GrB_finalize()
     return GrB_Info(ccall(dlsym(graphblas_lib, "GrB_finalize"), Cint, (), ))
 end

src/Object_Methods/Algebra_Methods.jl

@@ -1,6 +1,64 @@
 import GraphBLASInterface:
         GrB_UnaryOp_new, GrB_BinaryOp_new, GrB_Monoid_new, GrB_Semiring_new
 
+"""
+    GrB_UnaryOp_new(op, fn, ztype, xtype)
+
+Initialize a GraphBLAS unary operator with a specified user-defined function and its types.
+The function should take a single value(x) & return an output(z), f(x) = z.
+
+# Examples
+```jldoctest
+julia> using GraphBLASInterface, SuiteSparseGraphBLAS
+
+julia> GrB_init(GrB_NONBLOCKING)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> u = GrB_Vector{Int64}()
+GrB_Vector{Int64}
+
+julia> GrB_Vector_new(u, GrB_INT64, 3)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> I = [0, 2]; X = [10, 20]; n = 2;
+
+julia> GrB_Vector_build(u, I, X, n, GrB_FIRST_INT64)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> w = GrB_Vector{Int64}()
+GrB_Vector{Int64}
+
+julia> GrB_Vector_new(w, GrB_INT64, 3)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> function NEG(a)
+           return -a
+       end
+NEG (generic function with 1 method)
+
+julia> negative = GrB_UnaryOp()
+GrB_UnaryOp
+
+julia> GrB_UnaryOp_new(negative, NEG, GrB_INT64, GrB_INT64)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> GrB_apply(w, GrB_NULL, GrB_NULL, negative, u, GrB_NULL)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> @GxB_fprint(w, GxB_COMPLETE)
+
+GraphBLAS vector: w 
+nrows: 3 ncols: 1 max # entries: 2
+format: standard CSC vlen: 3 nvec_nonempty: 1 nvec: 1 plen: 1 vdim: 1
+hyper_ratio 0.0625
+GraphBLAS type:  int64_t size: 8
+number of entries: 2 
+column: 0 : 2 entries [0:1]
+    row 0: int64 -10
+    row 2: int64 -20
+
+```
+"""
 function GrB_UnaryOp_new(
     op::GrB_UnaryOp,
     fn::Function,
@@ -26,6 +84,55 @@ function GrB_UnaryOp_new(
             )
 end
 
+"""
+    GrB_BinaryOp_new(op, fn, ztype, xtype, ytype)
+
+Initialize a GraphBLAS binary operator with a specified user-defined function and its types.
+The function should take 2 values(x, y) & return an output(z), f(x, y) = z.
+
+# Examples
+```jldoctest
+julia> using GraphBLASInterface, SuiteSparseGraphBLAS
+
+julia> GrB_init(GrB_NONBLOCKING)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> V = GrB_Vector{Float64}()
+GrB_Vector{Float64}
+
+julia> GrB_Vector_new(V, GrB_FP64, 4)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> I = [0, 0, 3, 3]; X = [2.1, 3.2, 4.5, 5.0]; n = 4;  # two values at position 0 and 3
+
+julia> dup = GrB_BinaryOp()  # dup is a binary operator which is applied when duplicate values for the same location are present in the vector
+GrB_BinaryOp
+
+julia> function ADD(b, c)
+           return b+c
+       end
+ADD (generic function with 1 method)
+
+julia> GrB_BinaryOp_new(dup, ADD, GrB_FP64, GrB_FP64, GrB_FP64)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> GrB_Vector_build(V, I, X, n, dup)
+GrB_SUCCESS::GrB_Info = 0
+
+julia> @GxB_Vector_fprint(V, GxB_SHORT) # the value stored at position 0 and 3 will be the sum of the duplicate values
+
+GraphBLAS vector: V
+nrows: 4 ncols: 1 max # entries: 2
+format: standard CSC vlen: 4 nvec_nonempty: 1 nvec: 1 plen: 1 vdim: 1
+hyper_ratio 0.0625
+GraphBLAS type:  double size: 8
+number of entries: 2
+column: 0 : 2 entries [0:1]
+    row 0: double 5.3
+    row 3: double 9.5
+
+```
+"""
 function GrB_BinaryOp_new(
     op::GrB_BinaryOp,
     fn::Function,
@@ -52,6 +159,11 @@ function GrB_BinaryOp_new(
             )
 end
 
+"""
+    GrB_Monoid_new(monoid, binary_op, identity)
+
+Initialize a GraphBLAS monoid with specified binary operator and identity value.
+"""
 function GrB_Monoid_new(monoid::GrB_Monoid, binary_op::GrB_BinaryOp, identity::T) where T
     monoid_ptr = pointer_from_objref(monoid)
     fn_name = "GrB_Monoid_new_" * suffix(T)
@@ -108,6 +220,11 @@ function GrB_Monoid_new(monoid::GrB_Monoid, binary_op::GrB_BinaryOp, identity::F
             )
 end
 
+"""
+    GrB_Semiring_new(semiring, monoid, binary_op)
+
+Initialize a GraphBLAS semiring with specified monoid and binary operator.
+"""
 function GrB_Semiring_new(semiring::GrB_Semiring, monoid::GrB_Monoid, binary_op::GrB_BinaryOp)
     semiring_ptr = pointer_from_objref(semiring)
 

src/Object_Methods/Descriptor_Methods.jl

@@ -1,6 +1,11 @@
 import GraphBLASInterface:
         GrB_Descriptor_new, GrB_Descriptor_set
 
+"""
+    GrB_Descriptor_new(desc)
+
+Initialize a descriptor with default field values.
+"""
 function GrB_Descriptor_new(desc::GrB_Descriptor)
     desc_ptr = pointer_from_objref(desc)
 
@@ -14,6 +19,11 @@ function GrB_Descriptor_new(desc::GrB_Descriptor)
         )
 end
 
+"""
+    GrB_Descriptor_set(desc, field, val)
+
+Set the content for a field for an existing descriptor.
+"""
 function GrB_Descriptor_set(desc::GrB_Descriptor, field::GrB_Desc_Field, val::GrB_Desc_Value)
     return GrB_Info(
         ccall(

src/Object_Methods/Free_Objects.jl

@@ -2,6 +2,11 @@ import GraphBLASInterface:
         GrB_UnaryOp_free, GrB_BinaryOp_free, GrB_Monoid_free, GrB_Semiring_free,
         GrB_Vector_free, GrB_Matrix_free, GrB_Descriptor_free
 
+"""
+    GrB_UnaryOp_free(unaryop)
+
+Free unary operator.
+"""
 function GrB_UnaryOp_free(unaryop::GrB_UnaryOp)
     unaryop_ptr = pointer_from_objref(unaryop)
 
@@ -15,6 +20,11 @@ function GrB_UnaryOp_free(unaryop::GrB_UnaryOp)
         )
 end
 
+"""
+    GrB_BinaryOp_free(binaryop)
+
+Free binary operator.
+"""
 function GrB_BinaryOp_free(binaryop::GrB_BinaryOp)
     binaryop_ptr = pointer_from_objref(binaryop)
 
@@ -28,6 +38,11 @@ function GrB_BinaryOp_free(binaryop::GrB_BinaryOp)
         )
 end
 
+"""
+    GrB_Monoid_free(monoid)
+
+Free monoid.
+"""
 function GrB_Monoid_free(monoid::GrB_Monoid)
     monoid_ptr = pointer_from_objref(monoid)
 
@@ -41,6 +56,11 @@ function GrB_Monoid_free(monoid::GrB_Monoid)
         )
 end
 
+"""
+    GrB_Semiring_free(semiring)
+
+Free semiring.
+"""
 function GrB_Semiring_free(semiring::GrB_Semiring)
     semiring_ptr = pointer_from_objref(semiring)
 
@@ -54,6 +74,11 @@ function GrB_Semiring_free(semiring::GrB_Semiring)
         )
 end
 
+"""
+    GrB_Vector_free(v)
+
+Free vector.
+"""
 function GrB_Vector_free(v::GrB_Vector)
     v_ptr = pointer_from_objref(v)
 
@@ -67,6 +92,11 @@ function GrB_Vector_free(v::GrB_Vector)
         )
 end
 
+"""
+    GrB_Matrix_free(A)
+
+Free matrix.
+"""
 function GrB_Matrix_free(A::GrB_Matrix)
     A_ptr = pointer_from_objref(A)
 
@@ -80,6 +110,11 @@ function GrB_Matrix_free(A::GrB_Matrix)
         )
 end
 
+"""
+    GrB_Descriptor_free(desc)
+
+Free descriptor.
+"""
 function GrB_Descriptor_free(desc::GrB_Descriptor)
     desc_ptr = pointer_from_objref(desc)