docdates

Author: rayegun

docs/src/api.md

@@ -0,0 +1,6 @@
+!!! danger "Public vs Private API"
+    All docstrings are collected on this page. **However**, only assume exported functions and types are part of the public API. 
+
+```@autodocs
+Modules = [SuiteSparseGraphBLAS, UnaryOps, BinaryOps, Monoids, Semirings, GB_KLU]
+```

docs/src/arrays.md

@@ -24,9 +24,9 @@ The `GBMatrix` is an opaque sparse matrix structure, which adapts to the sparsit
 3. **Sparse Compressed** - [Compressed Sparse Column (CSC)](http://netlib.org/linalg/html_templates/node92.html#SECTION00931200000000000000) or [Compressed Sparse Row(CSR)](http://netlib.org/linalg/html_templates/node91.html)
 4. **Doubly Compressed** or **Hypersparse** - Doubly Compressed Sparse Column (DCSC or Hypersparse CSC) and Doubly Compressed Sparse Row (DCSR or Hypersparse CSR). See this paper for more information: [pdf](https://people.eecs.berkeley.edu/~aydin/hypersparse-ipdps08.pdf).
 
-Additionally a when the stored values in a `GBMatrix` are uniform the value array may be stored in the **iso** version of one of the formats above. Rather than storing the full value array, an iso `GBMatrix` will only store the single scalar to improve performance. This is useful for matrices like the unweighted adjacency matrix, where all stored values may be `true`. 
+Additionally, when the stored values in a `GBMatrix` are uniform the value array may be stored in the **iso** version of one of the formats above. Rather than storing the full value array, an iso `GBMatrix` will only store the single scalar to improve performance. This is useful for matrices like the unweighted adjacency matrix, where all stored values may be `true`. 
 
-Users should never need to directly interact with the underlying storage format, SuiteSparse:GraphBLAS will automatically convert between them as necessary.
+Users should rarely need to directly interact with the underlying storage format, SuiteSparse:GraphBLAS will automatically convert between them as necessary.
 
 ### Construction
 

docs/src/binaryops.md

@@ -5,7 +5,7 @@ However, the vast majority of binary operators are defined on a single domain.
 
 `BinaryOp`s are in almost every GraphBLAS operation. They are the primary `op` argument for [`emul`](@ref), [`eadd`](@ref), and [`apply`](@ref). `BinaryOp`s which are also monoids may be used in [`reduce`](@ref). And every GraphBLAS operation which takes an `accum` keyword argument accepts a `BinaryOp`.
 
-In 99% of cases you should pass Julia functions, which will be mapped to built-in operators, or used to create a new user-defined operator.
+In almost all cases you should pass Julia functions, which will be mapped to built-in operators, or used to create a new user-defined operator.
 
 ```@repl
 using SuiteSparseGraphBLAS

docs/src/index.md

@@ -36,7 +36,7 @@ A simple BFS is just a matrix-vector multiplication, where `A` is the adjacency
 
 ## GBArrays
 
-The core SuiteSparseGraphBLAS.jl array types are `GBVector` and `GBMatrix` which are subtypes `SparseArrays.AbstractSparseVector` and `SparseArrays.AbstractSparseMatrix` respectively. There are also several auxiliary array types that restrict one or more behaviors, like row or column orientation. More info on those types can be found ### HERE ###
+The core SuiteSparseGraphBLAS.jl array types are `GBVector` and `GBMatrix` which are subtypes `SparseArrays.AbstractSparseVector` and `SparseArrays.AbstractSparseMatrix` respectively.
 
 !!! note "GBArray"
     These docs will often refer to the `GBArray` type, which is the union of `AbstractGBVector`, `AbstractGBMatrix` and their lazy Transpose objects.
@@ -68,7 +68,7 @@ Different matrices may be better suited to storage in one of those formats, and
     The default orientation of a `GBMatrix` is by-row, the opposite of Julia arrays. However, a `GBMatrix` constructed from a `SparseMatrixCSC` or 
     `Matrix` will be stored by-column.\
     The orientation of a `GBMatrix` can be modified using
-    `gbset(A, :format, :byrow)` or `gbset(A, :format, :bycol)`, and queried by `gbget(A, :format)`
+    `setstorageorder!(A, RowMajor())` or `setstorageorder!(A, ColMajor())`, and queried by `StorageOrders.storageorder(A)`
 
 Information about storage formats, orientation, conversion, construction and more can be found in [Arrays](@ref).
 
@@ -151,9 +151,6 @@ map(increment, M)
 Unfortunately this has a couple problems. The first is that it's slow.\
 Compared to `A .+ 1` which lowers to `apply(+, A, 1)` the `map` call above is ~2.5x slower due to function pointer overhead.
 
-The second is that everytime we call `map(increment, M)` we will be re-creating the function pointer for `increment` matched to the type of `M`.\
-To avoid this the convenience macro `@unop` will provide a permanent constant which is used internally every time `increment` is called with a GraphBLAS operation. See [Operators](@ref) for more information.
-
 !!! warning "Performance of User Defined Functions"
     Operators which are not already built-in are automatically constructed using function pointers when called. 
     Note, however, that their performance is significantly degraded compared to built-in operators,
@@ -187,7 +184,7 @@ sandia(M)
 
 # Citing
 
-Please cite the following papers:
+Please cite the following papers if you use SuiteSparseGraphBLAS.jl in your work:
 
 [pdf](https://doi.org/10.1145/3322125):
 ```bibtex

docs/src/monoids.md

@@ -5,7 +5,7 @@ This binary operator must be associative, that is $f(a, f(b, c)) = f(f(a, b), c)
 
 The operator is also be equipped with an identity such that $f(x, 0) = f(0, x) = x$. Some monoids are equipped with a terminal or annihilator such that $z = f(z, x) \forall x$.
 
-Monoids are used primarily in the `reduce`(@ref) operation. Their other use is as a component of semirings in the [`mul!`](@ref) operation.
+Monoids are used primarily in the [`reduce`](@ref) operation. Their other use is as a component of semirings in the [`mul!`](@ref) operation.
 
 ## Built-Ins
 
@@ -25,4 +25,8 @@ Monoids are used primarily in the `reduce`(@ref) operation. Their other use is a
 | `∧`            | `LAND_MONOID`  | identity: `true`, term: `false`                                       |
 |                |                |                                                                       |
 |                |                |                                                                       |
-|                |                |                                                                       |
+|                |                |                                                                       |
+
+```@docs
+Monoid
+```

docs/src/operations.md

@@ -64,8 +64,9 @@ The accumulation step is performed **before** masking.
 ### `mask` - `GBArray`:
 
 The `mask` keyword argument determines whether each index from the result of an operation appears in the output. 
-The mask may be structural, where the presence of a value indicates the mask is `true`, or valued where the value of the mask indicates its truth value. 
-The mask may also be complemented. These options are controlled by the `desc` argument.
+The mask may be structural, where the presence of a value indicates the mask is `true`, or valued where the value of the mask indicates its truth value. `mask = SuiteSparseGraphBLAS.Structural(A)` will use a structural mask.
+
+The mask may also be complemented. `mask = SuiteSparseGraphBLAS.Complement(A)` or `mask = ~A` will complement a mask. These two options may be combined, for example `mask = ~SuiteSparseGraphBLAS.Structural(A)`.
 
 
 ## Operation Documentation

docs/src/operators.md

@@ -8,18 +8,21 @@ One is an extension to the `v1.3` specification: `SelectOp`.
 !!! danger "Note"
     Operators are **not** callable objects like functions. They **do** behave like functions when used as arguments to higher-order functions (operations in the language of GraphBLAS).
 
+    Operators are no longer first class objects in SuiteSparseGraphBLAS.jl v0.8. Only Monoids
+    require direct user interaction.
+
 Typically operators are positional arguments in one of two places.
 For operations with a clear default operator they appear as the last positional argument:
 
-- [`emul(A, B, op::Union{BinaryOp, Function})`](@ref emul)
-- [`eadd(A, B, op::Union{BinaryOp, Function})`](@ref eadd)
-- [`kron(A, B, op::Union{BinaryOp, Function})`](@ref kron)
-- [`*(A, B, op::Union{Semiring, Tuple{Function, Function}})`](@ref *)
+- [`emul(A, B, op::Function)`](@ref emul)
+- [`eadd(A, B, op::Function)`](@ref eadd)
+- [`kron(A, B, op::Function)`](@ref kron)
+- [`*(A, B, op::Tuple{Function, Function})`](@ref *)
 
 For other operations without a clear default operator they appear as the first argument:
 
-- [`apply(op::Union{UnaryOp, Function}, A)`](@ref apply)
-- [`reduce(op::Union{BinaryOp, Function}, A)`](@ref reduce)
+- [`apply(op::Function, A)`](@ref apply)
+- [`reduce(op::Union{Monoid, Function}, A)`](@ref reduce)
 - [`select(op::Union{SelectOp, Function}, A)`](@ref select)
 
 !!! note "Built-in vs User-defined operators"
@@ -43,42 +46,6 @@ SuiteSparseGraphBLAS.jl natively supports the following types:
 - Float32 and Float64
 - ComplexF32 and ComplexF64
 
-### Lowering
-
-Operators are lowered from a Julia function to a container like `BinaryOp` or `Semiring`. After this they are lowered once again using the type to a `TypedBinaryOp`, `TypedSemiring`, etc. The `TypedBinaryOp` contains the reference to the C-side GraphBLAS operator. Typed operators, like `TypedSemiring` are constants, found in a submodule (`SuiteSparseGraphBLAS.Semirings` in the case of `TypedSemiring`s).
-
-```@setup operators
-using SuiteSparseGraphBLAS
-```
-```@repl operators
-b = binaryop(+, Int32)
-
-s = Semiring(max, +)
-s(Float64)
-```
-
-All operations should accept the function/tuple form, the `Semiring{typeof(max), typeof(+)}` form, or the `TypedSemiring` form.
-Unless you need to specifically cast the arguments to a specific type there is generally no need to use the latter two forms.
-
-You can determine the the input and output types of a type-specific operator with the functions below:
-
-```@docs
-xtype
-ytype
-ztype
-```
-
-Some examples of these functions are below. 
-Note the difference between `ISGT` which returns a result with the same type as the input, and `GT` which returns a `Boolean`.
-
-```@repl operators
-xtype(Semirings.LOR_GT_UINT16)
-ztype(Semirings.LOR_GT_FP64)
-xtype(BinaryOps.ISGT_INT8)
-ztype(BinaryOps.ISGT_INT8)
-ztype(BinaryOps.GT_INT8)
-```
-
 ## SelectOps
 
 The [`SelectOp`](@ref) is a SuiteSparse extension to the specification, although a similar construct is likely to be found in a future specification.

docs/src/semirings.md

@@ -8,10 +8,8 @@ The second, $\otimes$ or "multiply", is a binary operator defined on $D_1 \times
 
 A semiring is denoted by a tuple $(D_1, D_2, D_3, \oplus, \otimes, \mathbb{0})$. However in the vast majority of cases $D_1 = D_2 = D_3$ so this is often shortened to $(\oplus, \otimes)$.
 
-Semirings are used in a single GraphBLAS operation, [`mul!`](@ref).
+Semirings are used in two GraphBLAS operations, `mul!` and [`*`](@ref).
 
 ## Passing to Functions
 
-`mul!` and `*` are the only functions which accept semirings, and the best method to do so is a tuple of binary functions like `*(A, B, (max, +))`. An operator form is also available as `*(min, +)(A, B)`.
-
-Semiring objects may be constructed in a similar fashion: `Semiring(max, +)`.
+`mul!` and `*` are the only functions which accept semirings, and the best method to do so is a tuple of binary functions like `*(A, B, (max, +))`. An operator form is also available as `*(min, +)(A, B)`.

docs/src/unaryops.md

@@ -21,7 +21,7 @@ using SuiteSparseGraphBLAS
 
 op = unaryop(sin, Float64)
 
-map(typedop, GBVector([1.5, 0, pi]))
+map(op, GBVector([1.5, 0, pi]))
 ```
 
 ## Built-Ins

docs/src/utilities.md

@@ -1,10 +1,18 @@
 ```@docs
 setfill
 setfill!
+sparsitystatus
+format
+setstorageorder!
 mask
 mask!
 gbset
 Descriptor
 SuiteSparseGraphBLAS.set_lib!
 empty!
+Complement
+Structural
+xtype
+ytype
+ztype
 ```