Oh, you sweet summer child, there is no level of ease for the average programmer that will make him or her want to document things… ;)
On a more serious note, good documentation for parameters in any tool that’s not stupidly simple tends to be more than a one liner if one doesn’t assume that the user already knows a ton of context (for example, imagine explaining “chmod” parameters with just one liners)
You can write more than one line but one line is usually enough for each of the options in the --help output. Obviously that doesn’t explain everything and especially not background like “how do unix permissions work” in your example but the --help output is not the correct place for that kind of information anyway.
The point is that a programmer would first need to think about what needs to be explained or not to the average user and then explain it properly, none of which is considered as interesting as coding.
It’s not by chance that even tools with actual one line of explanation for each parameter are general of the badly documented kind (I especially like the ones were the “help” for a command doesn’t say what the bloody command actually does).
I mean, you even see this kind of meaningless “documentation” in API documentation for widelly used libraries were the documentations is generated from comments embedded in the code: “public void doStuff(int height)” => “Does stuff. Parameters - height: the input height”.
I might have put it in a humouristic way but this quite a well-known and widespread phenomenon.
Oh, you sweet summer child, there is no level of ease for the average programmer that will make him or her want to document things… ;)
On a more serious note, good documentation for parameters in any tool that’s not stupidly simple tends to be more than a one liner if one doesn’t assume that the user already knows a ton of context (for example, imagine explaining “chmod” parameters with just one liners)
You can write more than one line but one line is usually enough for each of the options in the --help output. Obviously that doesn’t explain everything and especially not background like “how do unix permissions work” in your example but the --help output is not the correct place for that kind of information anyway.
The point is that a programmer would first need to think about what needs to be explained or not to the average user and then explain it properly, none of which is considered as interesting as coding.
It’s not by chance that even tools with actual one line of explanation for each parameter are general of the badly documented kind (I especially like the ones were the “help” for a command doesn’t say what the bloody command actually does).
I mean, you even see this kind of meaningless “documentation” in API documentation for widelly used libraries were the documentations is generated from comments embedded in the code: “public void doStuff(int height)” => “Does stuff. Parameters - height: the input height”.
I might have put it in a humouristic way but this quite a well-known and widespread phenomenon.