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]>
JuliaCI · Sep 18, 2023 · 58cf141 · 58cf141
1 parent c0a7157
commit 58cf141
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 2 deletions.
diff --git a/docs/src/manual.md b/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):
 

diff --git a/docs/src/reference.md b/docs/src/reference.md
@@ -7,4 +7,6 @@ Private = false
 
 ```@docs
 Base.run
+BenchmarkTools.save
+BenchmarkTools.load
 ```
diff --git a/src/serialization.jl b/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