Move some documentation into unsafe_buffers.md

Move some text from unsafe_buffers_paths.txt into the markdown file
so that it may be more easily discovered. Hidden benefit of not
reading and discarding so many comment lines in each compiler
invocation.

Re-arrange and re-write sections to make flow more natural.

Change-Id: I077cf0d91cdd52a36cde9bb7c882ce3cf1fd6785
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6251406
Reviewed-by: Daniel Cheng <[email protected]>
Reviewed-by: Arthur Sonzogni <[email protected]>
Commit-Queue: Tom Sepez <[email protected]>
Cr-Commit-Position: refs/heads/main@{#1418875}
NOKEYCHECK=True
GitOrigin-RevId: d647d84dc800a3cce6b8bbbc3ecfb4a22ceb0aa8

Author: tsepez

config/unsafe_buffers_paths.txt

@@ -2,52 +2,6 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
-# The set of path prefixes that should be checked for unsafe pointer usage (see
-# -Wunsafe-buffer-usage in Clang).
-#
-# ***
-# Paths should be written as relative to the root of the source tree with
-# unix-style path separators. Directory prefixes should end with `/`, such
-# as `base/`.
-# ***
-#
-# Lines that begin with `-` name path prefixes that will *not* be checked for
-# unsafe-buffer-usage. They are known to do unsafe things and should be
-# changed to use constructs like base::span or containers like base::HeapArray
-# and std::vector instead. See https://crbug.com/40285824
-#
-# Lines that begin with `+` name path prefixes that have no unsafe-buffer-usage
-# (or all such usage is annotated), and are protected against new unsafe pointer
-# behaviour by the compiler.
-#
-# By default, all files are checked for unsafe-buffer-usage unless they are
-# match a `-` path prefix line here. If a file matches both a `-` and `+` line,
-# the `+` line takes precedence and the file will be checked.
-#
-# To opt individual files out of checks, place `#pragma allow_unsafe_buffers`
-# anywhere in the (source or header) file, guarded by
-# `#ifdef UNSAFE_BUFFERS_BUILD`. These pragmas represent the technical debt and
-# security risk present in the file through unsafe pointer usage.
-#
-# ***
-# Recommended process for removing a `-dir/` line from this file:
-#
-# 1. Remove the `-dir/` line from this paths file.
-#    a. Possibly add some subdirectories if needed to reduce scope,
-#       like `-dir/sub_dir/`.
-# 2. Add `#pragma allow_unsafe_buffers` to every file in the directory that now
-#    has a compilation error, with a TODO to the tracking bug for the
-#    directory:
-#    ```
-#    #ifdef UNSAFE_BUFFERS_BUILD
-#    // TODO(crbug.com/ABC): Remove this and convert code to safer constructs.
-#    #pragma allow_unsafe_buffers
-#    #endif
-#    ```
-# 3. Work through the files in the directory, converting pointers to spans, or
-#    to owning containers like HeapArray and vector. Remove the pragmas from
-#    the files when there is no unsafe pointer usage left in each one.
-#
 # See `docs/unsafe_buffers.md`.
 
 -base/allocator/