[docs] Explain noexcept policy for narrow contracts.

[zoecarver]

Summary

Adds documentation around libc++'s policy to add noexcept to things that cannot throw but aren't marked as noexcept.

Refs LWG 3518 and D95251.

[curdeius]

libcxx/docs/UsingLibcxx.rst

355

Why not 13?

[zoecarver]

libcxx/docs/UsingLibcxx.rst

355

Has the 13 release branch already been created? Even if it hasn't yet, almost all of the changes won't follow this "new" policy, so I think 14 makes more sense.

If you'd still prefer I change it to 13, I'm happy to do that, though.

[curdeius]

libcxx/docs/UsingLibcxx.rst

355

Release branch 12.x has been created a few days ago. So current main is version 13. It will be released in circa 6 months. I guess you thought it was one higher.

[zoecarver]

libcxx/docs/UsingLibcxx.rst

355

Ah, I see, yes, I did think it was one higher.

[Mordante]

Can you also update the ReleaseNotes with this change in behaviour?

libcxx/docs/UsingLibcxx.rst

356

A bit pedantic, but it seems the Standard capitalizes Nothing.

357

This sentence is quite long. Maybe add a full stop throwing and user-provided -> throwing. User-provided

361

When adjusting 14 to 13, also change it here.

[ldionne]

libcxx/docs/UsingLibcxx.rst

352

I think this should move to libcxx/docs/DesignDocs/<something>.rst. You can then reference it (like the other design docs) from the main rst file.

355

Instead of wording this as "libc++ *will* mark functions that do not throw as noexcept", I think we should instead say something like: It is acceptable to mark functions that do not throw as noexcept. That way, we say that we are allowed to do it and we may use that right, but we don't *have* to. As worded currently, it sounds like people could file bugs against us for not following our own design policy to the letter. Do you see the distinction?

356

I think your closing parens is not in the right place. I think you mean this instead:

"Throws: Nothing") as noexcept.

[zoecarver]

libcxx/docs/UsingLibcxx.rst

355

Yes, I see the distinction, and I think you're right.

I'd kind of like to say that going forward we *will* mark these functions as noexcept, but I understand that might not be a reasonable thing to do (or at least not reasonable to do right now).

I updated the text to use 'may'/'might' rather than 'will'.

[zoecarver]

• Address review comments

[zoecarver]

• Add newline to UsingLibcxx.rst

[zoecarver]

libcxx/docs/DesignDocs/NoexceptPolicy.rst

15 ↗

(On Diff #320938)

Now that we just say that we might mark some functions as noexcept, we might not need this paragraph, what do you think?

[ldionne]

LGTM with paragraph removed. This is small, but it's important to record these decisions/policies by writing somewhere so that we can apply them mechanically in the future and avoid wasting time. Thanks!

libcxx/docs/DesignDocs/NoexceptPolicy.rst

15 ↗

(On Diff #320938)

Agreed.

libcxx/docs/UsingLibcxx.rst

 * ``none_of``
 * ``remove_if``
 * ``remove``
 * ``search_n``
 * ``search``
 * ``unique``
 * ``upper_bound``
 * ``lock_guard``'s constructors
+
+.. _noexcept extension:
+
+Extended applications of ``noexcept``
+------------------------------------------
+
+As of version 14 libc++ will mark functions that do not throw (i.e.,
+"Throws: nothing" as ``noexcept``). This means that functions will not
+report precondition violations by throwing and user-provided functions,
+such as custom predicates or custom traits, which throw will not be
+propagated up to the caller (unless specified otherwise by the standard).
+
+Before version 14, libc++ did not specify whether a function that did not
+throw would be marked as ``noexcept``, so users should not rely on any
+non-throwing functions to be marked ``noexcept`` (unless the standard
+specifies it).
 No newline at end of file