@hugovk Thanks for the feedback!

Would one of the following be clearer?

1. “List of strings to parse, processed from left to right.”
2. “List of strings to parse, in the order they appear.”
3. “List of strings to parse; arguments are processed sequentially.”

Happy to update the wording to your preference.

Respectively?

The discourse discussion was mostly about the fact that a list arg, as opposed to an iterable arg, could be processed in reverse, for instance by popping, or in any order. In the example use of argparse, the order mattered. The OP and others would like a order guarantee. This seems sensible to me.

My original suggested addition, "in normal order", meant "in normal left to right order" or equivalently, "in normal iteration order". I personally would go with the last, but Savannah can choose.

Thanks for the clarification — that makes sense.

I’ll update the wording to explicitly state that the arguments are processed in normal iteration (left-to-right) order, to reflect the intended guarantee discussed on Discourse.

I understand you want a guarantee to point to, but I'm not sure if this is really adding much to improve the docs.

Our style guide says:

More documentation is not necessarily better documentation. Err on the side of being succinct.

It is an unfortunate fact that making documentation longer can be an impediment to understanding and can result in even more ways to misread or misinterpret the text. Long descriptions full of corner cases and caveats can create the impression that a function is more complex or harder to use than it actually is.

If it's just for the benefit of the open-source project who want a guarantee, you can point them at this DPO thread, issue or PR. And it looks like they were satisfied with the DPO thread: zephyrproject-rtos/zephyr#101888 (comment).

If we really do need to clarify this (do we?), I don't think 3-4 words help much, and it should be explained in a bit more detail, perhaps with a brief example.

Thanks for the thoughtful feedback — that’s fair.

I agree that keeping the documentation concise is important. My intent here was simply to make the ordering guarantee explicit for readers who might otherwise assume the input could be processed in an arbitrary order, as discussed on Discourse.

That said, I’m very happy to adjust or simplify the wording further (or remove it if needed) in line with the documentation style guidance — I’ll follow whatever direction you think is most appropriate here.