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

Make spec neutral regarding array-of-table naming style #938

Merged

Conversation

ChristianSi
Copy link
Contributor

@ChristianSi ChristianSi commented Nov 10, 2022

This PR is an outcome of #932. Right now the spec only uses the "plural" naming conventions in its array-of-tables examples. However, it is far from clear that this is the only legitimate convention in such cases. Consider as example:

[[planets]]
name = "Mercury"
aphelion = 0.466697
radius = 2440

[[planets]]
name = "Venus"
aphelion = 0.728213
radius = 6052

This might seem unintuitive and perhaps even confusing to the reader or editor of the TOML file, since each [[...]] section header is only followed by a single instance of the described item (a planet, in this case). This can be made clearer by using the "singular" naming convention instead, and prominent TOML users such as Cargo do indeed use the "singular" naming style for arrays of tables (in Cargo: [[bin]], [[example]], [[test]], and [[bench]]).

The spec, however, currently uses the "plural" naming style in all its array-of-table examples, which may give the impression that that's the normal and preferred naming style. This PR makes the spec "neutral" in that regard, by switching one example (the "product[s]" example) to singular style, while leaving the other example (the "fruits" example) in plural style. This should make it clearer that either style is fine.

Why modify the "products" rather than the "fruits" example? I have no strong preference here; I choose the former simply because it's the smaller change (it only has three section headers, while the "fruits" example has six). But I would be happy to adapt the latter instead if that's for some reason preferred.

Put the "products" array-of-table example into singular to avoid giving the
impression that the "plural" style is the only legitimate and expected one.
@ChristianSi
Copy link
Contributor Author

@pradyunsg @mojombo What do you think? Could you take a took and merge this if it's good?

Copy link
Member

@pradyunsg pradyunsg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, why not.

@pradyunsg pradyunsg merged commit 913ff56 into toml-lang:main Dec 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants