Add document section of [dependencies]

[ya7010]

Hi 👋

I am developing Tombi, a TOML Language Server.

Tombi features automatic sorting based on JSON Schema and rigorously auto-sorts Cargo.toml files.

There are several ways to specify the automatic sorting order in Tombi.
One method is to automatically sort based on the order of properties defined in the JSON Schema.
For elements like [package] and [workspace], the JSON Schema order is adjusted to follow the sequence defined in Cargo's documentation.

However, the current Cargo [dependencies] documentation does not have the element list.
If Cargo's documentation also lists the order for [dependencies], it would lend credibility to Tombi's automatic sorting sequence.

Cargo documentation isn't written with automatic sorting in mind, but I think it's a source that explains what the official appearance should be.

I'd like to submit a PR to update the documentation, but I want to know what the cargo maintainers think.

[weihanglo]

FWIW, there is a official experimental JSON schema for the manifest. This is the detailed form of a dependency section:

cargo/crates/cargo-util-schemas/manifest.schema.json

Lines 757 to 880 in 81c3f77

	"TomlDetailedDependency": {
	"type": "object",
	"properties": {
	"version": {
	"type": [
	"string",
	"null"
	]
	},
	"registry": {
	"type": [
	"string",
	"null"
	]
	},
	"registry-index": {
	"description": "The URL of the `registry` field.\nThis is an internal implementation detail. When Cargo creates a\npackage, it replaces `registry` with `registry-index` so that the\nmanifest contains the correct URL. All users won't have the same\nregistry names configured, so Cargo can't rely on just the name for\ncrates published by other users.",
	"type": [
	"string",
	"null"
	]
	},
	"path": {
	"type": [
	"string",
	"null"
	]
	},
	"base": {
	"type": [
	"string",
	"null"
	]
	},
	"git": {
	"type": [
	"string",
	"null"
	]
	},
	"branch": {
	"type": [
	"string",
	"null"
	]
	},
	"tag": {
	"type": [
	"string",
	"null"
	]
	},
	"rev": {
	"type": [
	"string",
	"null"
	]
	},
	"features": {
	"type": [
	"array",
	"null"
	],
	"items": {
	"type": "string"
	}
	},
	"optional": {
	"type": [
	"boolean",
	"null"
	]
	},
	"default-features": {
	"type": [
	"boolean",
	"null"
	]
	},
	"default_features": {
	"type": [
	"boolean",
	"null"
	]
	},
	"package": {
	"type": [
	"string",
	"null"
	]
	},
	"public": {
	"type": [
	"boolean",
	"null"
	]
	},
	"artifact": {
	"description": "One or more of `bin`, `cdylib`, `staticlib`, `bin:<name>`.",
	"anyOf": [
	{
	"$ref": "#/$defs/StringOrVec"
	},
	{
	"type": "null"
	}
	]
	},
	"lib": {
	"description": "If set, the artifact should also be a dependency",
	"type": [
	"boolean",
	"null"
	]
	},
	"target": {
	"description": "A platform name, like `x86_64-apple-darwin`",
	"type": [
	"string",
	"null"
	]
	}
	}
	},

For documentation improvement, I am unsure how we want to approach this. I feel like the order of heading is the current order of importance, though there is not stability there and could change at any time. Do you have any idea what you want to approach it?

[epage]

Note there is an official style guide for rust which includes a Cargo section but I wouldn't follow it at this time as it needs a major revamp, see https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/.60Cargo.2Etoml.60.20style.20guide/with/380796244.

CC @joshtriplett

[ya7010]

Thank you for telling me that.

For documentation improvement, I am unsure how we want to approach this. I feel like the order of heading is the current order of importance, though there is not stability there and could change at any time. Do you have any idea what you want to approach it?

Tombi's auto-sorting can be configured at a granular level.
For example, it can be configured to always place default at the beginning of the dependencies.*.features.

Using schemars enables automatic generation of JSON Schema, including instructions for automatic sorting.
(We can reference the schema for tombi.toml)

I am considering updating the official documentation to reflect the automatic sort order, and automatically generating the JSON schema from rust source code.
The order may change in the future, but it should stabilize after incorporating some feedback(like tombi-toml/tombi#1023).
(New items added are a separate matter.)

[ya7010]

Note: Tombi determines automatic sorting by adding special x-tombi-* keys to JSON Schema.
https://tombi-toml.github.io/tombi/docs/json-schema#formatting

[weihanglo]

Note that the sorting part is marked as S-blocked-external since it may require Style team to make the final call #13313. We can do Cargo documentation improvement if it makes sense standalone, but we don't guarantee any stability around the order of sections in the Cargo doc. See also similar #15285.