Page MenuHomePhabricator

[docs] Explain noexcept policy for narrow contracts.
ClosedPublic

Authored by zoecarver on Feb 1 2021, 2:15 PM.

Details

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.

Diff Detail

Event Timeline

zoecarver requested review of this revision.Feb 1 2021, 2:15 PM
zoecarver created this revision.
Herald added a project: Restricted Project. · View Herald TranscriptFeb 1 2021, 2:15 PM
Herald added a reviewer: Restricted Project. · View Herald Transcript
curdeius added inline comments.
libcxx/docs/UsingLibcxx.rst
355

Why not 13?

zoecarver added inline comments.Feb 2 2021, 9:51 AM
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 added inline comments.Feb 2 2021, 10:06 AM
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 added inline comments.Feb 2 2021, 10:07 AM
libcxx/docs/UsingLibcxx.rst
355

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

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 requested changes to this revision.Feb 2 2021, 12:14 PM
ldionne added inline comments.
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.

This revision now requires changes to proceed.Feb 2 2021, 12:14 PM
zoecarver added inline comments.Feb 2 2021, 3:38 PM
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 updated this revision to Diff 320936.Feb 2 2021, 3:38 PM
  • Address review comments
zoecarver updated this revision to Diff 320938.Feb 2 2021, 3:39 PM
  • Add newline to UsingLibcxx.rst
zoecarver added inline comments.Feb 2 2021, 3:41 PM
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 accepted this revision.Feb 5 2021, 7:38 AM

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.

This revision is now accepted and ready to land.Feb 5 2021, 7:38 AM