From 20f3d10cd331f8da2b56b34eff973f19fb0f0eba Mon Sep 17 00:00:00 2001
From: Morten Piibeleht <morten.piibeleht@gmail.com>
Date: Sat, 6 Jul 2024 23:33:37 +1200
Subject: [PATCH] update docstrings

---
 src/codeblock.jl | 10 ++++++++--
 src/replblock.jl | 38 +++++++++++++++++++++++++++++++++++++-
 src/sandbox.jl   |  8 ++------
 3 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/src/codeblock.jl b/src/codeblock.jl
index e245a7f..558d3dd 100644
--- a/src/codeblock.jl
+++ b/src/codeblock.jl
@@ -1,7 +1,13 @@
 """
-    CodeEvaluation.codeblock!(sandbox::Sandbox, code::AbstractString) -> Result
+    CodeEvaluation.codeblock!(sandbox::Sandbox, code::AbstractString; kwargs...) -> Result
 
-...
+Evaluates a block of Julia code `code` in the `sandbox`, as if it is included as
+a script. Returns a [`Result`](@ref) object, containing the result of the evaluation.
+
+# Keywords
+
+- `color::Bool=true`: determines whether or not to capture colored output (i.e. controls
+  the IOContext).
 """
 function codeblock!(sandbox::Sandbox, code::AbstractString; color::Bool=true)
     exprs = CodeEvaluation.parseblock(code)
diff --git a/src/replblock.jl b/src/replblock.jl
index 9f96d97..1cf1f4c 100644
--- a/src/replblock.jl
+++ b/src/replblock.jl
@@ -1,3 +1,17 @@
+"""
+    struct CodeBlock
+
+Represents a single block in a sequence of REPL inputs and outputs in the [`REPLResult`](@ref) object.
+
+# Properties
+
+- `input::Bool`: whether this block represents a REPL input (i.e. an input `julia>`) or an output
+  from the REPL (either the plain string representation of the object, or the standard output or error
+  stream contents).
+
+- `code::String`: the contents of the block
+
+"""
 struct CodeBlock
     input::Bool
     code::String
@@ -5,6 +19,17 @@ end
 
 """
     struct REPLResult
+
+The result from a [`replblock!`](@ref) evaluation. It contains a sequence of input and output blocks.
+The inputs and outputs are separated, so that it would be easy for the users to style them differently
+if that is needed.
+
+See also: [`CodeBlock`](@ref), [`join_to_string`](@ref).
+
+# Properties
+
+- `sandbox :: Sandbox`: The `Sandbox` object in which the code was evaluated.
+- `blocks :: Vector{CodeBlock}`: The sequence of input and output block text.
 """
 struct REPLResult
     sandbox::Sandbox
@@ -22,11 +47,22 @@ function join_to_string(result::REPLResult)
 end
 
 """
-    CodeEvaluation.replblock!(sandbox::Sandbox, code::AbstractString) -> REPLResult
+    CodeEvaluation.replblock!(sandbox::Sandbox, code::AbstractString; kwargs...) -> REPLResult
 
 Evaluates the code in a special REPL-mode, where `code` gets split up into expressions,
 each of which gets evaluated one by one. The output is a string representing what this
 would look like if each expression had been evaluated in the REPL as separate commands.
+
+See also: [`REPLResult`](@ref), [`join_to_string`](@ref).
+
+# Keywords
+
+- `color::Bool=true`: determines whether or not to capture colored output (i.e. controls
+  the IOContext).
+
+- `post_process_inputs`: a function that can be used to post-process the input expressions.
+  It does not affect the code that is evaluated, just what gets included in the REPL input
+  blocks.
 """
 function replblock!(
     sandbox::Sandbox, code::AbstractString;
diff --git a/src/sandbox.jl b/src/sandbox.jl
index 81359f5..b613f98 100644
--- a/src/sandbox.jl
+++ b/src/sandbox.jl
@@ -70,12 +70,8 @@ Returns the name of the underlying module of the `Sandbox` object.
 """
 Base.nameof(sandbox::Sandbox) = nameof(sandbox.m)
 
-"""
-    abstract type AbstractValue end
-
-Will either [`AnsValue`](@ref) if the code evaluated successfully, or [`ExceptionValue`](@ref)
-if it did not.
-"""
+# Will either be [`AnsValue`](@ref) if the code evaluated successfully,
+# or [`ExceptionValue`](@ref) if it did not.
 abstract type AbstractValue end
 
 struct AnsValue <: AbstractValue