Add example usages in documentation

Author: jmert

Project.toml

@@ -1,7 +1,7 @@
 name = "UnixMmap"
 uuid = "674b2976-56af-439b-a2b1-837be4a3d087"
 authors = ["Justin Willmert <justin@willmert.me> and contributors"]
-version = "0.1.1"
+version = "1.0.0"
 
 [deps]
 BitFlags = "d1d4a3ce-64b1-5f1a-9ba4-7e7e69966f35"

README.md

@@ -9,24 +9,42 @@ exposing the Unix memory-mapping interface.
 
 ### Installation and usage
 
-This library is **not** registered in Julia's [General registry][General.jl],
-so the package must be installed either by cloning it directly:
+Installation and loading is as easy as:
+```julia
+pkg> add UnixMmap
 
-```
-(@v1.6) pkg> add https://github.com/jmert/UnixMmap.jl
-```
-
-or by making use of my [personal registry][Registry.jl]:
-
-```
-(@v1.6) pkg> registry add https://github.com/jmert/Registry.jl
-(@v1.6) pkg> add UnixMmap
+julia> using UnixMmap
 ```
 
-After installing, just load like any other Julia package:
-
+A file can be memory mapped (read-only by default) by giving the filename and the `Array`
+type (optionally with dimensions to give a shape):
+```julia
+julia> UnixMmap.mmap("arbitrary.dat", Array{Float64})
+192-element Vector{Float64}:
+ 0.0
+ 0.0
+ ⋮
+ 0.0
+ 0.0
+
+julia> UnixMmap.mmap("arbitrary.dat", Array{Float64}, (64, 3))
+64×3 Matrix{Float64}:
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+ ⋮
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
 ```
-julia> using UnixMmap
+while an anonymous memory map can be created by instead specifying the `Array` type and
+dimensions:
+```julia
+julia> UnixMmap.mmap(Array{Float64}, (128, 3))
+128×3 Matrix{Float64}:
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+ ⋮
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
 ```
 
 [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg

docs/src/index.md

@@ -1,5 +1,66 @@
 # UnixMmap.jl Documentation
 
+Installation and loading is as easy as:
+```julia-repl
+pkg> add UnixMmap
+
+julia> using UnixMmap
+```
+
+A file can be memory mapped (read-only by default) by calling [`UnixMmap.mmap`](@ref)
+with a filename and the `Array` type to be applied (and optionally with dimensions to give a
+shape):
+```julia-repl
+julia> UnixMmap.mmap("arbitrary.dat", Array{Float64})
+192-element Vector{Float64}:
+ 0.0
+ 0.0
+ ⋮
+ 0.0
+ 0.0
+
+julia> UnixMmap.mmap("arbitrary.dat", Array{Float64}, (64, 3))
+64×3 Matrix{Float64}:
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+ ⋮
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+```
+while an anonymous memory map can be created by instead specifying the `Array` type and
+dimensions:
+```julia-repl
+julia> UnixMmap.mmap(Array{Float64}, (128, 3))
+128×3 Matrix{Float64}:
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+ ⋮
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+```
+
+The notable features that UnixMmap.jl provides over the standard library's Mmap module
+is the ability to set Unix-specific flags during mapping.
+For example, on Linux the `MAP_POPULATE` flag can be used to advise the kernel to
+prefault all mapped pages into active memory.
+```julia-repl
+julia> UnixMmap.mmap("arbitrary.dat", Array{Float64}, (64, 3);
+                     flags = UnixMmap.MAP_SHARED | UnixMmap.MAP_POPULATE)
+64×3 Matrix{Float64}:
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+ ⋮
+ 0.0  0.0  0.0
+ 0.0  0.0  0.0
+```
+
+UnixMmap.jl provides OS-specific flags for several Unixes; see the
+[Constants](@ref Constants-—-Linux) section for more details.
+
+The package also exposes the [`UnixMmap.madvise!`](@ref), [`UnixMmap.msync!`](@ref), and
+[`UnixMmap.mincore`](@ref) functions which correspond closely to the underlying system
+calls.
+
 ## Library API Reference
 ```@contents
 Pages = [