doc bug: secrets, secret-envs and secret-files documentation is horrible

[breathe]

Contributing guidelines

• I've read the contributing guidelines and wholeheartedly agree

I've found a bug, and:

• The documentation does not mention anything about my problem
• There are no open or closed issues that are related to my problem

Description

The documentation written:

List of [secret files](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret) to expose to the build (e.g., key=filename, MY_SECRET=./secret.txt)

I think key=filename in each of these examples is supposed to be explaining that the only allowed syntax is key=value one per line. However as written these meanings are ridiculously unclear. The mapping from these settings to the 'normal' syntax for secrets via docker cli is not clear at all -- which makes the docs linked similarly unclear.

These examples should be rewritten to show the cli options that even a single example use of this feature would correspond to semantically ...

List of [secret files](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret) to expose to the build.  Example: `MY_SECRET=./secret.txt` translates to this cli `--secret id=MY_SECRET,type=file,src=./secret.txt`

Expected behaviour

The documentation would make it easy to interpret what values should be supplied

Actual behaviour

The documentation links to explanation that uses spelling with insufficient information to infer how to interpret that documentation from the source context.

Repository URL

No response

Workflow run URL

No response

YAML workflow

`secret-files:`

Workflow logs

No response

BuildKit logs

Additional info

No response

[crazy-max]

We have dedicated docs for GitHub Actions and secrets usage at https://docs.docker.com/build/ci/github-actions/secrets/

Manuals section also covers CLI usage: https://docs.docker.com/build/building/secrets/