Add better documentation, trigger namedtuple.

Add better documentation, trigger namedtuple.

Follow-up to https://codereview.chromium.org/2253943003:
  - Add much better comments to StepConfig fields.
  - Add rendering logic directly to StepConfig.
  - Add "cmd=[]" output to simulation results.
  - Make "trigger_specs" a namedtuple.

BUG=None
TEST=expectations

Committed: https://github.com/luci/recipes-py/commit/8ad49e0698f1e74e3f500fda6ca5b65a2af29fd0

[dnj, 2016-09-12 21:03:43]

dnj@chromium.org changed reviewers:
+ iannucci@chromium.org

[dnj, 2016-09-12 21:03:43]

PTAL, follow-up to: https://codereview.chromium.org/2337623002/

[iannucci, 2016-09-12 22:35:16]

lgtm

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py
File recipe_engine/recipe_api.py (right):

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:34: def _make_from_api_dict(cls, trig):
could we **explode this and add docstring?

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:41: assert isinstance(changes, list),
'buildbot_changes must be a list'
raise valueerror

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:55: raise KeyError('Unknown trigger spec keys: %s' %
(
I think this is still ValueError. I think KeyError is meant for "key is not in
the dictionary" type things.

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:107: ok_ret (iter): set of return codes allowed. If
the step process returns
if you want to say this is an iter, then we should also convert it to a
frozenset down below (since iter doesn't guarantee that it can be iterated over
repeatedly. A generator is an iter, for example).

[dnj, 2016-09-12 23:22:09]

The CQ bit was checked by dnj@chromium.org

[dnj, 2016-09-12 23:22:09]

The patchset sent to the CQ was uploaded after l-g-t-m from
iannucci@chromium.org
Link to the patchset: https://codereview.chromium.org/2332833003/#ps40001
(title: "More cleanups.")

[commit-bot: I haz the power, 2016-09-12 23:22:12]

CQ is trying da patch. Follow status at
 
https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...

[commit-bot: I haz the power, 2016-09-12 23:29:11]

Description was changed from

==========
Add better documentation, trigger namedtuple.

Follow-up to https://codereview.chromium.org/2253943003:
  - Add much better comments to StepConfig fields.
  - Add rendering logic directly to StepConfig.
  - Add "cmd=[]" output to simulation results.
  - Make "trigger_specs" a namedtuple.

BUG=None
TEST=expectations
==========

to

==========
Add better documentation, trigger namedtuple.

Follow-up to https://codereview.chromium.org/2253943003:
  - Add much better comments to StepConfig fields.
  - Add rendering logic directly to StepConfig.
  - Add "cmd=[]" output to simulation results.
  - Make "trigger_specs" a namedtuple.

BUG=None
TEST=expectations

Committed:
https://github.com/luci/recipes-py/commit/8ad49e0698f1e74e3f500fda6ca5b65a2af...
==========

[commit-bot: I haz the power, 2016-09-12 23:29:12]

Committed patchset #3 (id:40001) as
https://github.com/luci/recipes-py/commit/8ad49e0698f1e74e3f500fda6ca5b65a2af...

[dnj, 2016-09-12 23:30:11]

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py
File recipe_engine/recipe_api.py (right):

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:41: assert isinstance(changes, list),
'buildbot_changes must be a list'
On 2016/09/12 22:35:16, iannucci wrote:
> raise valueerror

Done.

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:55: raise KeyError('Unknown trigger spec keys: %s' %
(
On 2016/09/12 22:35:16, iannucci wrote:
> I think this is still ValueError. I think KeyError is meant for "key is not in
> the dictionary" type things.

Done.

https://codereview.chromium.org/2332833003/diff/1/recipe_engine/recipe_api.py...
recipe_engine/recipe_api.py:107: ok_ret (iter): set of return codes allowed. If
the step process returns
On 2016/09/12 22:35:16, iannucci wrote:
> if you want to say this is an iter, then we should also convert it to a
> frozenset down below (since iter doesn't guarantee that it can be iterated
over
> repeatedly. A generator is an iter, for example).

Was converting to a set, but frozenset is even better.

[martiniss, 2016-09-13 17:09:15]

martiniss@chromium.org changed reviewers:
+ martiniss@chromium.org

[martiniss, 2016-09-13 17:09:16]

https://codereview.chromium.org/2332833003/diff/40001/recipe_engine/recipe_ap...
File recipe_engine/recipe_api.py (right):

https://codereview.chromium.org/2332833003/diff/40001/recipe_engine/recipe_ap...
recipe_engine/recipe_api.py:796: self.helptext = helptext
This change is breaking all sorts of recipes downstream.

[martiniss, 2016-09-13 17:11:50]

A revert of this CL (patchset #3 id:40001) has been created in
https://codereview.chromium.org/2340483002/ by martiniss@chromium.org.

The reason for reverting is: help -> helptext change broke roller badly..