doc: General improvements.

recipe_engine/recipe_api.py

-# Copyright 2013-2015 The Chromium Authors. All rights reserved.
+# Copyright 2016 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 from __future__ import absolute_import
 import contextlib
 import keyword
 import re
 import types
 
 from functools import wraps
@@ skipping 215 matching lines @@
     with context({'aggregated_result': None, 'ran_step': [False]}):
       try:
         ret = func(*a, **kw)
         if not _STEP_CONTEXT.get('ran_step', [False])[0]:
           return ret
         agg.add_success(ret)
         return DeferredResult(ret, None)
       except StepFailure as ex:
         agg.add_failure(ex)
         return DeferredResult(None, ex)
+  _inner.__original = func

[martiniss, 2016/04/25 23:44:19]

Umm. Is this legit? It works, but.....

[iannucci, 2016/05/28 00:38:17]

it's as legit as anything else :/. Python's gone back and forth about how to do
this. To unwrap, you may need to recurse on __original's though.

   return _inner
 
 
 def composite_step(func):
   """A decorator which makes this step act as a single step, for the purposes of
   the defer_results function.
 
   This means that this function will not quit during the middle of its execution
   because of a StepFailure, if there is an aggregator active.
 
@@ skipping 17 matching lines @@
     # written in the same style (e.g. with exceptions) no matter how func is
     # being called.
     with context({'aggregated_result': None}):
       try:
         ret = func(*a, **kw)
         agg.add_success(ret)
         return DeferredResult(ret, None)
       except StepFailure as ex:
         agg.add_failure(ex)
         return DeferredResult(None, ex)
+  _inner.__original = func
   return _inner
 
 
 @contextlib.contextmanager
 def defer_results():
   """
   Use this to defer step results in your code. All steps which would previously
     return a result or throw an exception will instead return a DeferredResult.
 
   Any exceptions which were thrown during execution will be thrown when either:
@@ skipping 352 matching lines @@
     """
     Gets the BoundProperty version of this Property. Requires a name.
     """
     return BoundProperty(
         self._default, self.help, self.kind, name, property_type, module,
         self.param_name)
 
 class UndefinedPropertyException(TypeError):
   pass