MINOR: Fix docstring style

[alkis]

Rationale for this change

Make docstring style consistent.

What changes are included in this PR?

1. all comments are 80 cols wide
2. inline comments: // inline-comment
3. single line: /** single line */
4. multi line:

/**
 * multi
 * line
 */

5. when a field is deprecated we use DEPRECATED: ...
6. move deprecated structs to the end of the file

Do these changes have PoC implementations?

n/a.

[alkis]

FYI if it was up to me I would move away from java style and go to all // comments. This means less rules to follow and they would be more compact to boot. If reviewers are happy with this I can make the change.

[wgtmac]

I wonder if there is any good linter for thrift

[Fokko]

I would be reluctant to merge this because it rewrites a lot of history. Of course, you can still get to it by referencing the previous commit, but for a specification like this I think it is extra important to keep the history as clean as possible.

[alkis]

I would be reluctant to merge this because it rewrites a lot of history. Of course, you can still get to it by referencing the previous commit, but for a specification like this I think it is extra important to keep the history as clean as possible.

I can relate to the sentiment but I feel it applies more strongly to code. Documentation is less critical to have super clean history on.

[Fokko]

Thanks for raising this PR @alkis, but I'm going to close this one for now. For the thrift definitions, we don't want to lose the history, and if we want to have strict formatting, I think we should have an actual formatter to enforce the style.