--- a/s/Benchmark.st	Thu Oct 22 15:21:09 2015 +0100
+++ b/s/Benchmark.st	Fri Oct 30 07:19:59 2015 +0000
@@ -34,22 +34,44 @@
 !Benchmark class methodsFor:'running'!
 
 run
+    "Run all benchmarks in this class. Returns benchmark results as instance of BenchmarkResultC"
+
     ^ (BenchmarkSuite class:self) run
 
     "Created: / 10-06-2013 / 21:53:58 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified (comment): / 30-10-2015 / 07:05:27 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 run: benchmark
+    "Run benchmarks defined in method `benchmark` Returns benchmark result as instance of BenchmarkResultC"
+
     ^ (BenchmarkInstance class:self selector:benchmark) run
 
     "Created: / 31-05-2013 / 10:39:53 / Jan Vrany <jan.vrany@fit.cvut.cz>"
     "Modified: / 10-06-2013 / 21:53:44 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified (comment): / 30-10-2015 / 07:05:55 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 !
 
 run: benchmark with: parameters
+    "Run benchmark defined in method `benchmark` with given parameters.
+     Returns benchmark results as instance of BenchmarkResultC.
+     `parameters` id a Dictionary defining parameters and theit values
+     (as strings).
+     "          
+
     ^ (BenchmarkInstance class:self selector:benchmark) runWith: parameters
 
     "Created: / 10-03-2014 / 00:12:07 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+    "Modified (comment): / 30-10-2015 / 07:07:25 / Jan Vrany <jan.vrany@fit.cvut.cz>"
+!
+
+spy: benchmark
+    "Rum the benchmark under a Smalltalk profiler (MessageTally or whatever
+     the platform provides)."
+
+    ^ (BenchmarkInstance class:self selector:benchmark) spy
+
+    "Created: / 30-10-2015 / 07:16:16 / Jan Vrany <jan.vrany@fit.cvut.cz>"
 ! !
 
 !Benchmark class methodsFor:'testing'!

--- a/s/BenchmarkResultC.st	Thu Oct 22 15:21:09 2015 +0100
+++ b/s/BenchmarkResultC.st	Fri Oct 30 07:19:59 2015 +0000
@@ -9,6 +9,33 @@
 	category:'CalipeL-S-Core'
 !
 
+!BenchmarkResultC class methodsFor:'documentation'!
+
+documentation
+"
+    Instances of BenchmarkResultC hold results of benchmarks run, i.e., times, number of GCs
+    and other values collected by instruments.
+
+    For each benchmark, results are held in BenchmarkOutcome.
+
+    Note: The name of this class is rather stupid, but this is because of Pharo.
+    In Pharo 5.0 they introduced a class named BenchmarkResult, which is, indeed,
+    a completely different beast. To solve this name clash, 'C' has been appended
+    to denote this is 'Calipel''s version of BenchmarkResult.
+
+    [author:]
+        Jan Vrany <jan.vrany@fit.cvut.cz>
+
+    [instance variables:]
+
+    [class variables:]
+
+    [see also:]
+        BenchmarkOutcome
+        BenchmarkExecutor
+
+"
+! !
 
 !BenchmarkResultC class methodsFor:'instance creation'!