From 832657f1620704e7c487935e7e0363be3d908e1f Mon Sep 17 00:00:00 2001 From: Harald Alvestrand Date: Wed, 27 Apr 2022 08:59:32 +0000 Subject: [PATCH] Recommend using [[deprecated]] over ABSL_DEPRECATED Bug: none Change-Id: I6018fc75d347d610d078077e7b34131efaaef0db Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/260160 Commit-Queue: Harald Alvestrand Reviewed-by: Artem Titov Cr-Commit-Position: refs/heads/main@{#36696} --- g3doc/style-guide.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/g3doc/style-guide.md b/g3doc/style-guide.md index 62c99fc73b..421a7d9dc7 100644 --- a/g3doc/style-guide.md +++ b/g3doc/style-guide.md @@ -73,12 +73,12 @@ referencing a WebRTC bug, prefer the url form, e.g. ### Deprecation Annotate the declarations of deprecated functions and classes with the -[`ABSL_DEPRECATED` macro][ABSL_DEPRECATED] to cause an error when they're used +[`[[deprecated]]` attribute][DEPRECATED] to cause an error when they're used inside WebRTC and a compiler warning when they're used by dependant projects. Like so: ```cpp -ABSL_DEPRECATED("bugs.webrtc.org/12345") +[[deprecated("bugs.webrtc.org/12345")]] std::pony PonyPlz(const std::pony_spec& ps); ``` @@ -90,7 +90,7 @@ getting errors, do something like this: ```cpp std::pony DEPRECATED_PonyPlz(const std::pony_spec& ps); -ABSL_DEPRECATED("bugs.webrtc.org/12345") +[[deprecated("bugs.webrtc.org/12345")]] inline std::pony PonyPlz(const std::pony_spec& ps) { return DEPRECATED_PonyPlz(ps); } @@ -100,6 +100,12 @@ In other words, rename the existing function, and provide an inline wrapper using the original name that calls it. That way, callers who are willing to call it using the `DEPRECATED_`-prefixed name don't get the warning. +NOTE 3: Occasionally, with long descriptions, `git cl format` will do the wrong +thing with the attribute. In that case, you can use the +[`ABSL_DEPRECATED` macro][ABSL_DEPRECATED], which is formatted in a more +readable way. + +[DEPRECATED]: https://en.cppreference.com/w/cpp/language/attributes/deprecated [ABSL_DEPRECATED]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/abseil-cpp/absl/base/attributes.h?q=ABSL_DEPRECATED ### ArrayView