Its been said that the best documentation is source code. For UNIX I have always found this is solid advice. Whats nice about small programs, such as this one, is that its more feasible to use the source code as documentation.
"Anyway, for users ..."
Ah, thats me. I am a user. I personally love terse and cryptic, i.e., minimising the number of keys I have to press.
IME, multicall binaries like the OP presume some pre-existing knowledge of how to use the utilities they contain. It seems nonsensical to complain about missing documentation given the purpose of a multicall binary is to conserve space.
With BSD, the utilities in crunched binaries are generally the same ones, i.e., use the same source code, as in one in the userland. With GNU busybox, they are not, and one needs to read the source code to understand the differences.
Even if I can figure out how to use a program from reading documentation I still look at the source code before using it for the first time.
I keep wondering what it is that makes C programmers especially antisocial and obnoxious. Is it like in that joke:
Father calls his small son to him, pours a shot of vodka and tells him to drink it. The son drinks, then makes a face and says in repulse: “Eurgh, it's disgusting!”
The man replies: “Yeah, you probably thought your dad drinks honey, did you?”
That quotes simply means that you shouldn't write spaghetti code, and that another _programmer_ should be able to read it.
Quite clearly, it doesn't carry a meaning of: "hey, every user now has to become a proficient reader of whatever languages this software is written in."
Ah yes, the famed clarity and readability of C, where people are so entrenched in the belief that the compiler limits identifiers to seven characters or whatever, and in the aversion to typing out a single word in full, that they still build whole new languages with module, function and variable names looking like alphabet vomit. And with ungoogleable (ironically) language names to top it off.
I exclude man pages when I create systems with crunched binaries where I want to save space. The man pages are always available online. Its like djb's programs. They just refer the user to his website. I am not a programmer. I am the user. The small systems I create are for me and no one else, so naturally I make them according to personal preferences.
> Its been said that the best documentation is source code
fuck you. it's a myth perpetrated by lazy programmers, who can't be bothered to spend an hour or two writing a comprehensible usage manual, while otherwise EVERY USER IS GUARANTEED to spend MORE just figuring out how to BEGIN using his crap. It's only forgivable for the simplest of self-explanatory /API/ calls, but /nothing/ in userspace.
Posting like this will get you banned here, so please don't do that.
If you wouldn't mind reviewing https://news.ycombinator.com/newsguidelines.html and taking the intended spirit of the site more to heart, we'd be grateful. In particular, we don't want flamewars, and you've unfortunately already posted quite a few flamewar comments. Can you stick to thoughtful, curious comments instead? That's the kind of conversation we're trying for here. Note that that includes being respectful to whomever you're talking with, regardless of how wrong they are or you feel they are.
Documentation != user guide or manual. Manual are part of the documentation. And it is still true that the source code is the best documentation, ideally the source code can be used to automatically generate the docs. But overall documentation and things like ADR will hardly ever find their way into the source so require writing then externally.
I too am unskilled at navigating unfamiliar codebases and demand clifnotes because my time as a user is more valuable than yours as a programmer. these gift horses are AWFUL
"Anyway, for users ..."
Ah, thats me. I am a user. I personally love terse and cryptic, i.e., minimising the number of keys I have to press. IME, multicall binaries like the OP presume some pre-existing knowledge of how to use the utilities they contain. It seems nonsensical to complain about missing documentation given the purpose of a multicall binary is to conserve space.
With BSD, the utilities in crunched binaries are generally the same ones, i.e., use the same source code, as in one in the userland. With GNU busybox, they are not, and one needs to read the source code to understand the differences.
Even if I can figure out how to use a program from reading documentation I still look at the source code before using it for the first time.