WIP: more descriptions/comments for everything

[vbuterin]

Same as #1822 but fixed and rebased off of 0.12.

CC @hwwhww @protolambda

[protolambda]

It would be good to squash all these github edits, to keep the spec git history clean. If you are applying suggestions, there's also a "batch apply" function, to combine them.

[colekennelly1]

L

[hwwhww]

Redirect conversation to here:

@protolambda #1822 (comment):

The annotated spec by @benjaminion (And credit to many others, @djrtwo in particular) cannot go without mention here. Annotations and insightful comments are great, and make the spec much more readable, and hopefully enables more people to understand and audit it.

The spec has been "minimal" for a long time, often with others reducing the non-code text, but I really do think this PR is a step back in the right direction. However, it raises the question, how far should we go? More text than code?

It's a spec, and even calling them comments is wrong, they could be the majority of the spec. With a note that the code is the decision-maker, since it's not ambiguous unlike text can be. Preserving exact testable definitions through code is great.

cc @JustinDrake You have been the main proponent of minimalism, and although it was valuable to the spec, the text does not have to be like that. What do you think? And can this be a step towards the "Transparent Paper" (if that's how Eth2 as spec document will be called?).

@JustinDrake #1822 (comment)

cc @JustinDrake You have been the main proponent of minimalism, and although it was valuable to the spec, the text does not have to be like that. What do you think? And can this be a step towards the "Transparent Paper" (if that's how Eth2 as spec document will be called?).

Agreed that comments should make the spec maximally readable :) I haven't been able to deliver on the transparent paper for 1+ year so I wouldn't hold my breath on it 😂

[hwwhww]

Re: minimal spec

My 2 cents

1. It was a bit difficult to maintain the comments. e.g., the configuration was changed from 2**2 to 2**3, but the comment hasn’t been updated. But now, as the spec has been frozen to production mode, this issue should be minor than before.
2. More than one time, I found that some context was lost between the PRs and commits, so I had to git blame to find it. 😅 And sometimes, it was misconfigured. So IMHO having “some important comments” is appreciated.
3. I love Ben's annotated spec that explains the context detailedly, very much! So far, this PR is not too detailed or lengthy to me. I suppose we can refine the words with more iterations here...

[JustinDrake]

I'll take a look at this and make edits to the doc directly :)

[hwwhww]

@vbuterin
I guess new https://github.com/ethereum/annotated-spec repo would replace this PR?

[JustinDrake]

I guess new https://github.com/ethereum/annotated-spec repo would replace this PR?

Adding a link to the two annotated specs in this repo makes sense to me :)