[Docs] Inconsistency in yarn workspaces list --recursive documentation vs. actual behavior

[WooWan]

According to the documentation, --recursive option is described as:

Find packages via dependencies/devDependencies instead of using the workspaces field

However, based on code examination, it actually lists package dependents (packages that depend on the workspace), not its dependencies:

berry/packages/plugin-essentials/sources/commands/workspaces/list.ts

Lines 63 to 66 in 3c8a90a

	if (this.recursive)
	for (const dependents of [...candidates].map(candidate => candidate.getRecursiveWorkspaceDependents()))
	for (const dependent of dependents)
	workspaces.add(dependent);

This inconsistency becomes more confusing when comparing with yarn workspaces foreach, which has different behavior depending on whether --since is used with --recursive:

berry/packages/plugin-workspace-tools/sources/commands/foreach.ts

Lines 200 to 207 in 3c8a90a

	if (this.recursive) {
	if (this.since) {
	log(`Option --recursive --since is set; recursively selecting all dependent workspaces`);
	extra = new Set(selection.map(workspace => [...workspace.getRecursiveWorkspaceDependents()]).flat());
	} else {
	log(`Option --recursive is set; recursively selecting all transitive dependencies`);
	extra = new Set(selection.map(workspace => [...workspace.getRecursiveWorkspaceDependencies()]).flat());
	}

When both --recursive and --since are set in yarn workspaces foreach, it traverses dependents (like yarn workspaces list). But when only --recursive is set, it traverses dependencies instead.

This can be misleading for yarn newcomers(I am) who expect consistent behavior across commands. We should improve consistency and documentation to clearly reflect the actual behavior of each command.
While looking for previous discussions, I noticed this was mentioned in a yarn v4 issue, but I couldn't find any follow-up PRs or resolution.
It would be helpful to either update the documentation to correctly reflect the current behavior, or adjust the implementation to match the documented behavior.