From 0e60a75792d7db16d91d4de2f26922afa579cf34 Mon Sep 17 00:00:00 2001 From: Simon Giesecke Date: Tue, 3 Dec 2019 08:14:57 +0000 Subject: [PATCH] Bug 1600066 - Added clarification on use of already_AddRefed. r=dom-workers-and-storage-reviewers,janv,asuth Differential Revision: https://phabricator.services.mozilla.com/D55117 --HG-- extra : moz-landing-system : lando --- dom/docs/workersAndStorage/CodeStyle.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/dom/docs/workersAndStorage/CodeStyle.rst b/dom/docs/workersAndStorage/CodeStyle.rst index 6de6ab828a51..316e5b976834 100644 --- a/dom/docs/workersAndStorage/CodeStyle.rst +++ b/dom/docs/workersAndStorage/CodeStyle.rst @@ -164,8 +164,11 @@ We extend this by some more encouragements and discouragements: which will make the type information available in searchfox. In consequence, the guidelines might be amended to promote a more widespread use of ``auto``. +Pointer types +------------- + Plain pointers --------------- +~~~~~~~~~~~~~~ The use of plain pointers is error-prone. Avoid using owning plain pointers. In particular, avoid using literal, non-placement new. There are various kinds @@ -186,6 +189,20 @@ factory functions: | ``std::shared_ptr`` | ``std::make_shared`` | ```` | +------------------------+-------------------------+------------------------+ +Also, to create an ``already_AddRefed<>`` to pass as a parameter or return from +a function without the need to dereference it, use ``MakeAndAddRef`` instead of +creating a dereferenceable ``RefPtr`` (or similar) first and then using +``.forget()``. + +Smart pointers +~~~~~~~~~~~~~~ + +In function signatures, prefer accepting or returning ``RefPtr`` instead of +``already_AddRefed`` in conjunction with regular ``std::move`` rather than +``.forget()``. This improves readability and code generation. Prevailing +legimitate uses of ``already_AddRefed`` are described in its +`documentation `_. + Evolution Process =================