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

@@ -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``    | ``<memory>``           |
 +------------------------+-------------------------+------------------------+
 
+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 <https://searchfox.org/mozilla-central/rev/4df8821c1b824db5f40f381f48432f219d99ae36/mfbt/AlreadyAddRefed.h#31>`_.
+
 Evolution Process
 =================