fts: Correct description of fts_set

[des]

Summary

Reverts: e030e4e73fe7 ("lib/libc/gen/fts.3: use 'options' consistently in fts_set() description")
MFC after: 1 week
Sponsored by: Klara, Inc.

[asomers]

Why?

[des]

In D57326#1313542, @asomers wrote:

Why?

options was never correct, it has always been instr. I assume whoever first wrote the page copy-pasted fts_children() and forgot to adjust options to instr.

Crucially, functions that take an options argument accept multiple value bitwise-or'ed together, while fts_set() accepts only one value at a time.

[asomers]

In D57326#1313547, @des wrote:

In D57326#1313542, @asomers wrote:

Why?

options was never correct, it has always been instr. I assume whoever first wrote the page copy-pasted fts_children() and forgot to adjust options to instr.

Crucially, functions that take an options argument accept multiple value bitwise-or'ed together, while fts_set() accepts only one value at a time.

The prototype at the top of the man page documents the argument as being named "options". And the header file does not contradict that. So "options" is definitely the name of the argument, and change e030e4e73fe7 was correct. Whether it _should_ be named that is a different question. I would not describe this change of yours as a reversion.

[des]

In D57326#1313548, @asomers wrote:

In D57326#1313547, @des wrote:

In D57326#1313542, @asomers wrote:

Why?

options was never correct, it has always been instr. I assume whoever first wrote the page copy-pasted fts_children() and forgot to adjust options to instr.

Crucially, functions that take an options argument accept multiple value bitwise-or'ed together, while fts_set() accepts only one value at a time.

The prototype at the top of the man page documents the argument as being named "options". And the header file does not contradict that. So "options" is definitely the name of the argument, and change e030e4e73fe7 was correct. Whether it _should_ be named that is a different question. I would not describe this change of yours as a reversion.

I just explained to you that the prototype at the top of the page is incorrect. The header does not name the argument. The code names the argument instr and always has; options was never a reasonable name for this argument.

[asomers]

In D57326#1313561, @des wrote:

In D57326#1313548, @asomers wrote:

In D57326#1313547, @des wrote:

In D57326#1313542, @asomers wrote:

Why?

options was never correct, it has always been instr. I assume whoever first wrote the page copy-pasted fts_children() and forgot to adjust options to instr.

Crucially, functions that take an options argument accept multiple value bitwise-or'ed together, while fts_set() accepts only one value at a time.

The prototype at the top of the man page documents the argument as being named "options". And the header file does not contradict that. So "options" is definitely the name of the argument, and change e030e4e73fe7 was correct. Whether it _should_ be named that is a different question. I would not describe this change of yours as a reversion.

I just explained to you that the prototype at the top of the page is incorrect. The header does not name the argument. The code names the argument instr and always has; options was never a reasonable name for this argument.

The code doesn't matter; that's an implementation detail not visible to the user. The only user-visible name ever given for that argument was "options", in the prototype at the top of the man page. That prototype defined the argument name. So it was by definition correct.
Of course, that doesn't mean that it was a wisely-chosen name. Changing argument names is something we can do. But "changing the argument's name" it different than "revert the change that made the argument name consistent". This PR has a misleading commit message.