Yeah. I tend to feel like this is the kind of thing where it's not likely to be 100% obvious to users how it all works no matter what we put in the documentation, and that some of the behavior of a system has to be learned just by trying out the system.
I see where you are coming from and agree with a good portion of it, and accept that you are accurately representing reality for most of the rest, regardless of my feelings on that reality. I'm not invested in this enough to try and change mindsets. I have withdrawn the patch from the commitfest and do not plan on putting forth a replacement.
Thank you for your thorough review, I do appreciate it. It did reaffirm some of the suspicions I had about the wording I had chosen at least.
I will add that when I finished the patch I felt it was of more value to future developers than it would be to our end users. I never really worried that a patch could be written to fill in the missing pieces that prompted the various bug reports. I went to the extra effort because the underlying interactions seemed complicated and I wanted to see in practice exactly how they behaved and what that meant for usability. I also still disagree with our choice to emit an error on a namespace collision, and generally feel this area could use improvement. Thus I keep the tests around, which basically communicate that "this is how things work and it is intentional" and also are useful to have should future changes, however unlikely to materialize, be made. Sure, that isn't "regression" but in my unfamiliarity I didn't know of a better existing place to put them and didn't think to figure out (or create) a better location, one that doesn't run on every build.