Improve callRealMethod() documentation

[kriegaex]

Closes #830.

---

This change is 

[codecov]

Codecov Report

Merging #1005 into master will decrease coverage by 1.97%.
The diff coverage is 84.66%.

@@             Coverage Diff              @@
##             master    #1005      +/-   ##
============================================
- Coverage     75.99%   74.01%   -1.98%     
+ Complexity     3544     3434     -110     
============================================
  Files           377      382       +5     
  Lines         10788    10614     -174     
  Branches       1374     1297      -77     
============================================
- Hits           8198     7856     -342     
- Misses         2109     2294     +185     
+ Partials        481      464      -17

Impacted Files	Coverage Δ	Complexity Δ
...g/spockframework/junit4/AbstractRuleExtension.java	86.66% <ø> (ø)	10 <0> (?)
.../java/org/spockframework/runtime/SpockRuntime.java	71.11% <ø> (+2.03%)	20 <0> (-1)	⬇️
...n/java/spock/util/concurrent/BlockingVariable.java	93.75% <ø> (ø)	6 <0> (ø)	⬇️
...kframework/spring/mock/SpockMockPostprocessor.java	85.03% <ø> (+1.03%)	41 <0> (-1)	⬇️
...in/java/spock/util/concurrent/AsyncConditions.java	93.54% <ø> (ø)	9 <0> (ø)	⬇️
...pock-core/src/main/java/spock/mock/MockingApi.java	2.94% <ø> (ø)	2 <0> (ø)	⬇️
...k-core/src/main/java/spock/lang/Specification.java	84.21% <ø> (ø)	17 <0> (ø)	⬇️
spock-core/src/main/java/spock/lang/Retry.java	100% <ø> (ø)	0 <0> (ø)	⬇️
.../spockframework/report/log/ReportLogExtension.java	100% <ø> (+28.57%)	1 <0> (-7)	⬇️
...spockframework/runtime/SpockComparisonFailure.java	83.33% <ø> (ø)	3 <0> (ø)	⬇️
... and 118 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e9d1c3d...44669a2. Read the comment docs.

[terribleherbst]

I guess it is a good idea to extend the documentation and include semantic usage of features. Spys, Mocks and Stubs are very (technical) similar and therefor often mixed up.
This is a good improvement regarding the documentation.

[leonard84]

Thanks @kriegaex and sorry for the delay