(FWIW, I was also thinking that docs could be added in the README (probably under 'Usage'); & in addition to docs on what the options themselves do, maybe a pointer for folks using Docker Desktop to enable the 'Enable host networking' option)

edit: apparently I had the wrong idea of what -net was meant to achieve :p (IRC logs)

The -net option is documented in the same way all other options are documented, which is to say, it documented, but hard to reach. We should address that!

All options are currently documented in two places:

• Usage string when invoking the CLI.
• Option documentation, in the repo.

usage: fresh-node20 [-env-mw] [-env-bs] [-env-sauce] [env=PREFIX] [-net] [-root] [-podman] [-- command]
to run a command in the container, pass it after --

…
# Option: -env-mw
#   Forward `MW_*` and `MEDIAWIKI_*` environment variables from the host machine
#   to the Fresh container. This is designed for use with MediaWiki tests.
#   If an `.env` file exists in the current directory, its `MW_*` and `MEDIAWIKI_` entries
#   will also be read and forwarded to the container.
#   Note that the variables set in via `.env` take precedence over variables set at
#   runtime e.g. from `export` commands in `.bashrc`.
…
# Option: -net
#   This exposes network ports from the host machine to the Fresh container.
#   For example, to enable access to a MediaWiki web server.
#   https://docs.docker.com/network/network-tutorial-host/
…

Fresh is meant to be given zero trust. The security goal behind it means I expect users to audit it and make it feel their own when installing it. This is why the Fresh source is minimal, simple, human-readable, and self-contained. The readme encourages users to read the source.

The doc blocks shown above are specifically written for the end-user, and intentionally placed near the top of the file. (They're not inline comments about code, or otherwise aimed at maintainers.)

But.. there's a couple of flaws with this.

1. This usage string is only printed after you make a mistake, like fresh-node --whatever. That shouldn't be required for discovery of documentation. This is kind of true for most CLIs, and if you stab in the dark and run fresh-node --help, that does technically work and prints the usage string (albeit it alongside an error saying that "help" is not a valid option.) We should make --help a recognised option so that the error isn't printed there, and remind people in the README that --help exists.

2. Once you know which option you're likely interested in, it's not clear where to go. The usage string only mentions which options exist, not what they do in detail. I choose the names to be descriptive and clear enough to let you find what you're interested in. However, assuming you reviewed the code once in the past and were satisfied it couldn't do anything undesirable, that doesn't mean you'll remember forever what it does, or remember that it contains documentation for options you didn't know you'd want until later.

Documentation shouldn't be hard, and should surface itself within the tool. So, yeah... make a proper --help option!.

I suggest:

• Move the docblocks to the usage string.
• Recognise --help as a valid option (i.e. remove unknown option: --help from the --help output).
• Mention the --help option in the README so that you can easily (re-)discover it.

Change #1287901 had a related patch set uploaded (by LazyShrey; author: LazyShrey):

[fresh@master] fresh-node: Add proper --help docs

https://gerrit.wikimedia.org/r/1287901

I’ve submitted a patch to Gerrit for T424867:
https://gerrit.wikimedia.org/r/c/fresh/+/1287901

This adds a proper --help option for fresh-node, makes -h/--help recognized options, and adds a README note for discoverability.

@Krinkle any reviews for new patch?

Change #1287901 merged by jenkins-bot:

[fresh@master] fresh-node: Add proper --help docs

https://gerrit.wikimedia.org/r/1287901