Add Example Code to Common Workflow (#290)

* common workflow with examples

* use old_results variable

Co-authored-by: Guillaume Dalle <[email protected]>

* use old_results variable 2

Co-authored-by: Guillaume Dalle <[email protected]>

* use old_results variable 3

Co-authored-by: Guillaume Dalle <[email protected]>

* Add docstrings to load and save + tweak manual

---------

Co-authored-by: Guillaume Dalle <[email protected]>

Author: FelixBenning

docs/src/manual.md

@@ -888,10 +888,23 @@ A common workflow used in BenchmarkTools is the following:
 
 1. Start a Julia session
 2. Execute a benchmark suite using an old version of your package
-3. Save the results somehow (e.g. in a JSON file)
+    ```julia
+    old_results = run(suite, verbose = true)
+    ```
+4. Save the results somehow (e.g. in a JSON file)
+    ```julia
+    BenchmarkTools.save("old_results.json", old_results)
+    ```
 4. Start a new Julia session
 5. Execute a benchmark suite using a new version of your package
-6. Compare the new results with the results saved in step 3 to determine regression status
+   ```julia
+   results = run(suite, verbose = true)
+   ```
+7. Compare the new results with the results saved in step 3 to determine regression status
+    ```julia
+    old_results = BenchmarkTools.load("old_results.json")
+    BenchmarkTools.judge(minimum(results), minimum(old_results))
+    ```
 
 There are a couple of problems with this workflow, and all of which revolve around parameter tuning (which would occur during steps 2 and 5):
 

docs/src/reference.md

@@ -7,4 +7,6 @@ Private = false
 
 ```@docs
 Base.run
+BenchmarkTools.save
+BenchmarkTools.load
 ```

src/serialization.jl

@@ -89,6 +89,11 @@ function badext(filename)
     throw(ArgumentError(msg))
 end
 
+"""
+    BenchmarkTools.save(filename, args...)
+
+Save serialized benchmarking objects (e.g. results or parameters) to a JSON file.
+"""
 function save(filename::AbstractString, args...)
     endswith(filename, ".json") || badext(filename)
     open(filename, "w") do io
@@ -116,6 +121,11 @@ function save(io::IO, args...)
     return JSON.print(io, [VERSIONS, goodargs])
 end
 
+"""
+    BenchmarkTools.load(filename)
+
+Load serialized benchmarking objects (e.g. results or parameters) from a JSON file.
+"""
 function load(filename::AbstractString, args...)
     endswith(filename, ".json") || badext(filename)
     open(filename, "r") do f