Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: should object parameter properties be sorted? #22874

Closed
vsemozhetbyt opened this issue Sep 15, 2018 · 4 comments
Closed

doc: should object parameter properties be sorted? #22874

vsemozhetbyt opened this issue Sep 15, 2018 · 4 comments
Labels
discuss Issues opened for discussions and feedbacks. doc Issues and PRs related to the documentations.

Comments

@vsemozhetbyt
Copy link
Contributor

vsemozhetbyt commented Sep 15, 2018

Refs: #22824 (comment)

Pros:

  1. They will be easier to find in long lists.

Cons:

  1. Huge doc churn, git blame ruin, difficult diffs to review in correction PRs, significant backporting burdens.
  2. Hard to maintain in new PRs except it will be automated as doc lint rule.
  3. Some properties can be grouped logically, this grouping will be destroyed by ABC-sorting.

Please, vote:

+1 — 👍
-1 — 👎

Apart from the previous voting:

"I may be ready to review such PRs (one per doc to reduce the workload)" — 🎉

@vsemozhetbyt vsemozhetbyt added doc Issues and PRs related to the documentations. discuss Issues opened for discussions and feedbacks. labels Sep 15, 2018
@vsemozhetbyt
Copy link
Contributor Author

vsemozhetbyt commented Sep 15, 2018

(BTW, if approved, this can be done in some code-and-learn session, even one section per PR.)

@addaleax
Copy link
Member

I’m not a fan of breaking up logical grouping of properties. I get the “long lists” argument, but it’s not exactly like we have 10+ options or so on a regular basis…

@Trott
Copy link
Member

Trott commented Sep 17, 2018

It would be great if there was a way to have both a defined ordering and logical groupings, but I don't see an obvious way to achieve that.

@vsemozhetbyt
Copy link
Contributor Author

It seems we have not needed consensus on this case, so I will close the issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
discuss Issues opened for discussions and feedbacks. doc Issues and PRs related to the documentations.
Projects
None yet
Development

No branches or pull requests

3 participants