docs: Clarify corner caseses with default values

[epage]

This is meant to lower the chance of confusion with cases like #2714 and #1586

This is not meant to be exhaustive, looked at the mentioned cases in
that issue and pattern matched on other ones mentioning "is present".

When working on this, I wanted to make sure we limit our **NOTE:**s to not lower their value, so I moved the YAML description down into the examples which seems more fitting and some cases already do this.

[pksunkara]

NOTE: This argument is considered present when there is a [Arg::default_value]

I disagree with this. The initial implementation was very buggy because of incomplete design. We had fixed many of those bugs for v3 but it still behaves wrongly because of the original design.

What we need is a tiny bit refactor on the design for how this works to solve the linked issue. This is actually one of the reason why I have all those default value related issues marked as 3.0 (Let's keep continuing to discuss the deferral part in other places). They will all be fixed by this design refactor.

[epage]

NOTE: This argument is considered present when there is a [Arg::default_value]

I disagree with this. The initial implementation was very buggy because of incomplete design. We had fixed many of those bugs for v3 but it still behaves wrongly because of the original design.

What we need is a tiny bit refactor on the design for how this works to solve the linked issue.

That is best discussed in the Issue.

[pksunkara]

I looked at #2897 a bit more and I think I can get it done by the end of upcoming weekend. Let's wait on merging this until then.

[epage]

I looked at #2897 a bit more and I think I can get it done by the end of upcoming weekend. Let's wait on merging this until then.

I'd rather we not keep a branch long-lived for the sake of a possibility. If you end up fixing this, it can be reverted then.

[pksunkara]

Give me a few days as I asked. It's not long. I lose track of things that need reverts when I fix them.

[pksunkara]

Let's remove the second commit and merge this. #2714 and #1586 and #1906 are purely bugs in the conflict handling code. I have them fixed without even needing breaking changes.

[epage]

Let's remove the second commit and merge this. #2714 and #1586 and #1906 are purely bugs in the conflict handling code. I have them fixed without even needing breaking changes.

We can revert that commit when a fix becomes available.

bors r+

[pksunkara]

We don't add documentation when it is a big fix right?

[epage]

We don't add documentation when it is a big fix right?

We are documenting a pitfall within the current behavior. If/when that pitfall is removed, we can update it.

[bors]

Build succeeded:

• CI