--- a/docs/make.jl	Fri Jan 14 13:42:47 2022 +0100
+++ b/docs/make.jl	Fri Jan 14 15:39:56 2022 +0100
@@ -25,6 +25,7 @@
 
 pages = [
     "index.md",
+    "operator_file_format.md",
     "Submodules" => [
         "submodules/grids.md",
         "submodules/diff_ops.md",

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/operator_file_format.md	Fri Jan 14 15:39:56 2022 +0100
@@ -0,0 +1,72 @@
+# Operator file format
+
+The intention is that Sbplib.jl should be a general and extensible framework
+for working with finite difference methods. It therefore includes a set of
+tools for storing and sharing operator definitions as well as a set of widely
+used operators.
+
+## Using the included operators
+
+Most users will likely access the included operators by simply passing the
+filename of the wanted operator set to the appropriate function.  The location
+of the included stencil sets can be computed using
+[`sbp_operators_path`](@ref).
+```@meta
+# TODO: provide examples of functions to pass the files to
+```
+Advanced user might want to get access to the individual objects of an
+operator file. This can be accomplished using functions such as
+* [`read_stencil_set`](@ref)
+* [`parse_scalar`](@ref)
+* [`parse_stencil`](@ref)
+* [`parse_tuple`](@ref)
+
+When parsing operator objects they are interpreted using `Rational`s and
+possibly have to be converted to a desired type before use. This allows
+preserving maximum accuracy when needed.
+```@meta
+# TBD: "possibly have to be converted to a desired type before use" Is this the case? Can it be fixed?
+```
+
+## File format
+The file format is based on TOML and can be parsed using `TOML.parse`. A file
+can optionally start with a `[meta]` section which can specify things like who
+the author was, a description and how to cite the operators.
+
+After the `[meta]` section one or more stencil sets follow, each one beginning
+with `[[stencil_set]]`. Each stencil set should include descriptors like
+`order`, `name` or `number_of_bondary_points` to make them unique within the
+TOML-file. What descriptors to use are up to the author of the file to decide.
+
+Beyond identifying information the stencil set can contain any valid TOML.
+This data is then parsed by the functions creating specific operators like
+``D_1`` or ``D_2``.
+
+### Numbers
+Number can be represented as regular TOML numbers e.g. `1`, `-0.4` or
+`4.32e-3`. Alternatively they can be represented as strings which allows
+specifying fraction e.g. `"1/2"` or "0".
+
+All numbers are accurately converted to `Rational`s when using the
+[`parse_scalar`](@ref) function.
+
+### Stencils
+Stencils are parsed using [`parse_stencil`](@ref). They can be specified
+either as a simple arrays
+```toml
+stencil = ["-1/2","0", "1/2"]
+```
+which assumes a centered stencil. Or as a TOML inline table
+```toml
+stencil =  {s = ["-24/17", "59/34", "-4/17", "-3/34", "0", "0"], c = 1},
+```
+which allows specifying the center of the stencil using the key `c`.
+
+## Creating your own operator files
+Operator files can be created either to add new variants of existing types of
+operators like ``D_1`` or ``D_2`` or to describe completely new types of
+operators like for example a novel kind of interpolation operator. In the
+second case new parsing functions are also necessary.
+
+The files can then be used to easily test or share different variants of
+operators.

--- a/src/SbpOperators/readoperator.jl	Fri Jan 14 13:42:47 2022 +0100
+++ b/src/SbpOperators/readoperator.jl	Fri Jan 14 15:39:56 2022 +0100
@@ -10,10 +10,6 @@
 export sbp_operators_path
 
 
-# TODO: Docs for readoperator.jl
-    # Parsing as rationals is intentional, allows preserving exactness, which can be lowered using converts or promotions later.
-    # Documetning the format: Allows representing rationals as strings
-
 """
     read_stencil_set(fn; filters)
 
@@ -29,6 +25,8 @@
 general, and currently do not include any way to specify how to parse a given
 section, the exact parsing is left to the user.
 
+For more information see [Operator file format](@ref) in the documentation.
+
 See also [`sbp_operators_path`](@ref), [`get_stencil_set`](@ref), [`parse_stencil`](@ref), [`parse_scalar`](@ref), [`parse_tuple`](@ref),.
 """
 read_stencil_set(fn; filters...) = get_stencil_set(TOML.parsefile(fn); filters...)
@@ -62,7 +60,7 @@
 """
     parse_stencil(parsed_toml)
 
-Accepts parsed parsed_toml and reads it as a stencil
+Accepts parsed parsed_toml and reads it as a stencil.
 
 See also [`read_stencil_set`](@ref), [`parse_scalar`](@ref), [`parse_tuple`](@ref).
 """