[libcxx-commits] [libcxx] [libc++] Document the strengthened noexcept convention (PR #203869)

[Louis Dionne via libcxx-commits]

ldionne wrote:

> 
> > I actually think that having an easy way to check whether we stick to the standard or differ from it is quite valuable. As a matter of fact, this came up in a WG21 discussion last week, that's why I decided to tackle this.
> 
> That can easily be checked via libc++-specific checks, no?

Well, sure, you can create a godbolt that does `std::cout << noexcept(some-expression)` and check the values on various implementations, but you have to think about all of the possible places in the standard library we might have added it. Instead, this creates a cheap index of where we diverge from strict standards conformance.

> 
> > Well, once you know that something is strengthened, the task of figuring out in which ways it is strengthened is a lot easier than figuring out whether there's a diff from the standard in the first place. The point here is to call out places where we differ from the spec.
> 
> In what scenario do we care about this though? Once a lifetime during a discussion on when WG21 should add `noexcept`? (I assume that's where this came up.)

I think this comes up whenever the Lakos rule is discussed, including in our code reviews (especially containers and places where exception safety guarantees are important). I've often asked myself "can this thing throw?", and knowing whether a `noexcept` we have is required by the standard or just added by libc++ for whatever reason is helpful.

Sure, you can always open up the standard and look, but I think having a quick visual cue is helpful (and quite cheap). By the way, this investigation alone found a bunch of places where we were either missing noexcept or where noexcept was not tested, and I'll be submitting patches for that.

> 
> > Sometimes I like comment is the easiest way of documenting something. A unit test is useful to lock down the behaviour but that doesn’t stop the inline documentation from being useful
> 
> That assumes the inline documentation is correct and up-to-date, which it all too often isn't. I don't think I'd trust the comments if I ever actually needed to know for some reason, just like I never trust our synopsis comments. Also noteworthy is that the absence of such a comment doesn't tell me that a `noexcept` is actually not strengthened.

Pushing this argument to its logical conclusion suggests that we shouldn't write comments or documentation because it risks being out of date, unlike the code which is by definition "up to date". I strongly disagree with that general viewpoint, and I don't think it makes sense to invoke that general principle as an argument against this specific patch. In particular, this patch won't make it noticeably harder to keep our comments/documentation up to date (if anything, maybe the contrary). The status quo is that we do write helpful comments and documentation, and we do our best to keep them up to date -- and most people find that extremely useful.

> TL;DR I'm not convinced the comment gives me enough information (especially that I'd trust) to be meaningful to outweigh the cost.

Whether something is QOI-`noexcept` or not is already something that we discuss on code reviews. Adding these comments won't lead to any more work, it'll just force us to be more intentional and explicit about calling out where we put `noexcept` as QOI.

https://github.com/llvm/llvm-project/pull/203869