From 304d816cd351d3de19959cc2946153b37058023f Mon Sep 17 00:00:00 2001 From: Marshall Greenblatt Date: Mon, 5 Sep 2022 16:17:57 -0400 Subject: [PATCH] Format include/base comments for Doxygen (see issue #3384) --- Doxyfile | 3 +- include/base/cef_atomic_flag.h | 27 +- include/base/cef_atomic_ref_count.h | 48 +-- include/base/cef_bind.h | 404 +++++++++++++----------- include/base/cef_build.h | 64 ++-- include/base/cef_callback.h | 66 ++-- include/base/cef_callback_forward.h | 8 +- include/base/cef_callback_helpers.h | 83 +++-- include/base/cef_callback_list.h | 105 ++++--- include/base/cef_cancelable_callback.h | 89 +++--- include/base/cef_lock.h | 28 +- include/base/cef_logging.h | 228 +++++++------- include/base/cef_macros.h | 4 +- include/base/cef_platform_thread.h | 40 ++- include/base/cef_ptr_util.h | 8 +- include/base/cef_ref_counted.h | 147 +++++---- include/base/cef_scoped_refptr.h | 132 ++++---- include/base/cef_scoped_typeref_mac.h | 74 +++-- include/base/cef_thread_checker.h | 87 +++--- include/base/cef_trace_event.h | 414 ++++++++++++++----------- include/base/cef_tuple.h | 47 +-- include/base/cef_weak_ptr.h | 271 +++++++++------- 22 files changed, 1316 insertions(+), 1061 deletions(-) diff --git a/Doxyfile b/Doxyfile index f6a8a4a04..63797f4bc 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1038,8 +1038,7 @@ EXCLUDE_PATTERNS = *_internal.h # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = base::cef_internal \ - base::cef_subtle \ +EXCLUDE_SYMBOLS = base::cef_subtle \ base::internal \ cef_trace_event \ cef::logging diff --git a/include/base/cef_atomic_flag.h b/include/base/cef_atomic_flag.h index 3730838e7..3a2fdbc1d 100644 --- a/include/base/cef_atomic_flag.h +++ b/include/base/cef_atomic_flag.h @@ -49,9 +49,11 @@ namespace base { -// A flag that can safely be set from one thread and read from other threads. -// -// This class IS NOT intended for synchronization between threads. +/// +/// A flag that can safely be set from one thread and read from other threads. +/// +/// This class IS NOT intended for synchronization between threads. +/// class AtomicFlag { public: AtomicFlag(); @@ -61,19 +63,26 @@ class AtomicFlag { ~AtomicFlag(); - // Set the flag. Must always be called from the same thread. + /// + /// Set the flag. Must always be called from the same thread. + /// void Set(); - // Returns true iff the flag was set. If this returns true, the current thread - // is guaranteed to be synchronized with all memory operations on the thread - // which invoked Set() up until at least the first call to Set() on it. + /// + /// Returns true iff the flag was set. If this returns true, the current + /// thread is guaranteed to be synchronized with all memory operations on the + /// thread which invoked Set() up until at least the first call to Set() on + /// it. + /// bool IsSet() const { // Inline here: this has a measurable performance impact on base::WeakPtr. return flag_.load(std::memory_order_acquire) != 0; } - // Resets the flag. Be careful when using this: callers might not expect - // IsSet() to return false after returning true once. + /// + /// Resets the flag. Be careful when using this: callers might not expect + /// IsSet() to return false after returning true once. + /// void UnsafeResetForTesting(); private: diff --git a/include/base/cef_atomic_ref_count.h b/include/base/cef_atomic_ref_count.h index 8fb0cc608..38e8f93b7 100644 --- a/include/base/cef_atomic_ref_count.h +++ b/include/base/cef_atomic_ref_count.h @@ -58,19 +58,25 @@ class AtomicRefCount { explicit constexpr AtomicRefCount(int initial_value) : ref_count_(initial_value) {} - // Increment a reference count. - // Returns the previous value of the count. + /// + /// Increment a reference count. + /// Returns the previous value of the count. + /// int Increment() { return Increment(1); } - // Increment a reference count by "increment", which must exceed 0. - // Returns the previous value of the count. + /// + /// Increment a reference count by "increment", which must exceed 0. + /// Returns the previous value of the count. + /// int Increment(int increment) { return ref_count_.fetch_add(increment, std::memory_order_relaxed); } - // Decrement a reference count, and return whether the result is non-zero. - // Insert barriers to ensure that state written before the reference count - // became zero will be visible to a thread that has just made the count zero. + /// + /// Decrement a reference count, and return whether the result is non-zero. + /// Insert barriers to ensure that state written before the reference count + /// became zero will be visible to a thread that has just made the count zero. + /// bool Decrement() { // TODO(jbroman): Technically this doesn't need to be an acquire operation // unless the result is 1 (i.e., the ref count did indeed reach zero). @@ -79,23 +85,29 @@ class AtomicRefCount { return ref_count_.fetch_sub(1, std::memory_order_acq_rel) != 1; } - // Return whether the reference count is one. If the reference count is used - // in the conventional way, a refrerence count of 1 implies that the current - // thread owns the reference and no other thread shares it. This call - // performs the test for a reference count of one, and performs the memory - // barrier needed for the owning thread to act on the object, knowing that it - // has exclusive access to the object. + /// + /// Return whether the reference count is one. If the reference count is used + /// in the conventional way, a refrerence count of 1 implies that the current + /// thread owns the reference and no other thread shares it. This call + /// performs the test for a reference count of one, and performs the memory + /// barrier needed for the owning thread to act on the object, knowing that it + /// has exclusive access to the object. + /// bool IsOne() const { return ref_count_.load(std::memory_order_acquire) == 1; } - // Return whether the reference count is zero. With conventional object - // referencing counting, the object will be destroyed, so the reference count - // should never be zero. Hence this is generally used for a debug check. + /// + /// Return whether the reference count is zero. With conventional object + /// referencing counting, the object will be destroyed, so the reference count + /// should never be zero. Hence this is generally used for a debug check. + /// bool IsZero() const { return ref_count_.load(std::memory_order_acquire) == 0; } - // Returns the current reference count (with no barriers). This is subtle, and - // should be used only for debugging. + /// + /// Returns the current reference count (with no barriers). This is subtle, + /// and should be used only for debugging. + /// int SubtleRefCountForDebug() const { return ref_count_.load(std::memory_order_relaxed); } diff --git a/include/base/cef_bind.h b/include/base/cef_bind.h index 2e6a07169..7211ebf03 100644 --- a/include/base/cef_bind.h +++ b/include/base/cef_bind.h @@ -28,41 +28,42 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// ----------------------------------------------------------------------------- -// Usage documentation -// ----------------------------------------------------------------------------- -// -// Overview: -// base::BindOnce() and base::BindRepeating() are helpers for creating -// base::OnceCallback and base::RepeatingCallback objects respectively. -// -// For a runnable object of n-arity, the base::Bind*() family allows partial -// application of the first m arguments. The remaining n - m arguments must be -// passed when invoking the callback with Run(). -// -// // The first argument is bound at callback creation; the remaining -// // two must be passed when calling Run() on the callback object. -// base::OnceCallback cb = base::BindOnce( -// [](short x, int y, long z) { return x * y * z; }, 42); -// -// When binding to a method, the receiver object must also be specified at -// callback creation time. When Run() is invoked, the method will be invoked on -// the specified receiver object. -// -// class C : public base::RefCounted { void F(); }; -// auto instance = base::MakeRefCounted(); -// auto cb = base::BindOnce(&C::F, instance); -// std::move(cb).Run(); // Identical to instance->F() -// -// See //docs/callback.md for the full documentation. -// -// ----------------------------------------------------------------------------- +/// +/// \file +/// base::BindOnce() and base::BindRepeating() are helpers for creating +/// base::OnceCallback and base::RepeatingCallback objects respectively. +/// +/// For a runnable object of n-arity, the base::Bind*() family allows partial +/// application of the first m arguments. The remaining n - m arguments must be +/// passed when invoking the callback with Run(). +/// +/// 
+///   // The first argument is bound at callback creation; the remaining
+///   // two must be passed when calling Run() on the callback object.
+///   base::OnceCallback cb = base::BindOnce(
+///       [](short x, int y, long z) { return x * y * z; }, 42);
+///
+/// +/// When binding to a method, the receiver object must also be specified at +/// callback creation time. When Run() is invoked, the method will be invoked on +/// the specified receiver object. +/// +/// 
+///   class C : public base::RefCounted { void F(); };
+///   auto instance = base::MakeRefCounted();
+///   auto cb = base::BindOnce(&C::F, instance);
+///   std::move(cb).Run();  // Identical to instance->F()
+///
+/// +/// See https://chromium.googlesource.com/chromium/src/+/lkgr/docs/callback.md +/// for the full documentation. +/// + // Implementation notes -// ----------------------------------------------------------------------------- // // If you're reading the implementation, before proceeding further, you should -// read the top comment of base/internal/cef_bind_internal.h for a definition of -// common terms and concepts. +// read the top comment of base/internal/cef_bind_internal.h for a definition +// of common terms and concepts. #ifndef CEF_INCLUDE_BASE_CEF_BIND_H_ #define CEF_INCLUDE_BASE_CEF_BIND_H_ @@ -92,7 +93,9 @@ namespace base { -// Bind as OnceCallback. +/// +/// Bind as OnceCallback. +/// template inline OnceCallback> BindOnce( Functor&& functor, @@ -111,7 +114,9 @@ inline OnceCallback> BindOnce( std::forward(args)...); } -// Bind as RepeatingCallback. +/// +/// Bind as RepeatingCallback. +/// template inline RepeatingCallback> BindRepeating(Functor&& functor, Args&&... args) { @@ -123,9 +128,11 @@ BindRepeating(Functor&& functor, Args&&... args) { std::forward(args)...); } -// Special cases for binding to a base::Callback without extra bound arguments. -// We CHECK() the validity of callback to guard against null pointers -// accidentally ending up in posted tasks, causing hard-to-debug crashes. +/// +/// Special cases for binding to a base::Callback without extra bound arguments. +/// We CHECK() the validity of callback to guard against null pointers +/// accidentally ending up in posted tasks, causing hard-to-debug crashes. +/// template OnceCallback BindOnce(OnceCallback callback) { CHECK(callback); @@ -145,44 +152,54 @@ RepeatingCallback BindRepeating( return callback; } -// Unretained() allows binding a non-refcounted class, and to disable -// refcounting on arguments that are refcounted objects. -// -// EXAMPLE OF Unretained(): -// -// class Foo { -// public: -// void func() { cout << "Foo:f" << endl; } -// }; -// -// // In some function somewhere. -// Foo foo; -// OnceClosure foo_callback = -// BindOnce(&Foo::func, Unretained(&foo)); -// std::move(foo_callback).Run(); // Prints "Foo:f". -// -// Without the Unretained() wrapper on |&foo|, the above call would fail -// to compile because Foo does not support the AddRef() and Release() methods. +/// +/// Unretained() allows binding a non-refcounted class, and to disable +/// refcounting on arguments that are refcounted objects. +/// +/// EXAMPLE OF Unretained(): +/// +/// 
+///   class Foo {
+///    public:
+///     void func() { cout << "Foo:f" << endl; }
+///   };
+///
+///   // In some function somewhere.
+///   Foo foo;
+///   OnceClosure foo_callback =
+///       BindOnce(&Foo::func, Unretained(&foo));
+///   std::move(foo_callback).Run();  // Prints "Foo:f".
+///
+/// +/// Without the Unretained() wrapper on |&foo|, the above call would fail +/// to compile because Foo does not support the AddRef() and Release() methods. +/// template inline internal::UnretainedWrapper Unretained(T* o) { return internal::UnretainedWrapper(o); } -// RetainedRef() accepts a ref counted object and retains a reference to it. -// When the callback is called, the object is passed as a raw pointer. -// -// EXAMPLE OF RetainedRef(): -// -// void foo(RefCountedBytes* bytes) {} -// -// scoped_refptr bytes = ...; -// OnceClosure callback = BindOnce(&foo, base::RetainedRef(bytes)); -// std::move(callback).Run(); -// -// Without RetainedRef, the scoped_refptr would try to implicitly convert to -// a raw pointer and fail compilation: -// -// OnceClosure callback = BindOnce(&foo, bytes); // ERROR! +/// +/// RetainedRef() accepts a ref counted object and retains a reference to it. +/// When the callback is called, the object is passed as a raw pointer. +/// +/// EXAMPLE OF RetainedRef(): +/// +/// 
+///    void foo(RefCountedBytes* bytes) {}
+///
+///    scoped_refptr bytes = ...;
+///    OnceClosure callback = BindOnce(&foo, base::RetainedRef(bytes));
+///    std::move(callback).Run();
+///
+/// +/// Without RetainedRef, the scoped_refptr would try to implicitly convert to +/// a raw pointer and fail compilation: +/// +/// 
+///    OnceClosure callback = BindOnce(&foo, bytes); // ERROR!
+///
+/// template inline internal::RetainedRefWrapper RetainedRef(T* o) { return internal::RetainedRefWrapper(o); @@ -192,26 +209,30 @@ inline internal::RetainedRefWrapper RetainedRef(scoped_refptr o) { return internal::RetainedRefWrapper(std::move(o)); } -// Owned() transfers ownership of an object to the callback resulting from -// bind; the object will be deleted when the callback is deleted. -// -// EXAMPLE OF Owned(): -// -// void foo(int* arg) { cout << *arg << endl } -// -// int* pn = new int(1); -// RepeatingClosure foo_callback = BindRepeating(&foo, Owned(pn)); -// -// foo_callback.Run(); // Prints "1" -// foo_callback.Run(); // Prints "1" -// *pn = 2; -// foo_callback.Run(); // Prints "2" -// -// foo_callback.Reset(); // |pn| is deleted. Also will happen when -// // |foo_callback| goes out of scope. -// -// Without Owned(), someone would have to know to delete |pn| when the last -// reference to the callback is deleted. +/// +/// Owned() transfers ownership of an object to the callback resulting from +/// bind; the object will be deleted when the callback is deleted. +/// +/// EXAMPLE OF Owned(): +/// +/// 
+///   void foo(int* arg) { cout << *arg << endl }
+///
+///   int* pn = new int(1);
+///   RepeatingClosure foo_callback = BindRepeating(&foo, Owned(pn));
+///
+///   foo_callback.Run();  // Prints "1"
+///   foo_callback.Run();  // Prints "1"
+///   *pn = 2;
+///   foo_callback.Run();  // Prints "2"
+///
+///   foo_callback.Reset();  // |pn| is deleted.  Also will happen when
+///                          // |foo_callback| goes out of scope.
+///
+/// +/// Without Owned(), someone would have to know to delete |pn| when the last +/// reference to the callback is deleted. +/// template inline internal::OwnedWrapper Owned(T* o) { return internal::OwnedWrapper(o); @@ -223,78 +244,89 @@ inline internal::OwnedWrapper Owned( return internal::OwnedWrapper(std::move(ptr)); } -// OwnedRef() stores an object in the callback resulting from -// bind and passes a reference to the object to the bound function. -// -// EXAMPLE OF OwnedRef(): -// -// void foo(int& arg) { cout << ++arg << endl } -// -// int counter = 0; -// RepeatingClosure foo_callback = BindRepeating(&foo, OwnedRef(counter)); -// -// foo_callback.Run(); // Prints "1" -// foo_callback.Run(); // Prints "2" -// foo_callback.Run(); // Prints "3" -// -// cout << counter; // Prints "0", OwnedRef creates a copy of counter. -// -// Supports OnceCallbacks as well, useful to pass placeholder arguments: -// -// void bar(int& ignore, const std::string& s) { cout << s << endl } -// -// OnceClosure bar_callback = BindOnce(&bar, OwnedRef(0), "Hello"); -// -// std::move(bar_callback).Run(); // Prints "Hello" -// -// Without OwnedRef() it would not be possible to pass a mutable reference to an -// object owned by the callback. +/// +/// OwnedRef() stores an object in the callback resulting from +/// bind and passes a reference to the object to the bound function. +/// +/// EXAMPLE OF OwnedRef(): +/// +/// 
+///   void foo(int& arg) { cout << ++arg << endl }
+///
+///   int counter = 0;
+///   RepeatingClosure foo_callback = BindRepeating(&foo, OwnedRef(counter));
+///
+///   foo_callback.Run();  // Prints "1"
+///   foo_callback.Run();  // Prints "2"
+///   foo_callback.Run();  // Prints "3"
+///
+///   cout << counter;     // Prints "0", OwnedRef creates a copy of counter.
+///
+/// +/// Supports OnceCallbacks as well, useful to pass placeholder arguments: +/// +/// 
+///   void bar(int& ignore, const std::string& s) { cout << s << endl }
+///
+///   OnceClosure bar_callback = BindOnce(&bar, OwnedRef(0), "Hello");
+///
+///   std::move(bar_callback).Run(); // Prints "Hello"
+///
+/// +/// Without OwnedRef() it would not be possible to pass a mutable reference to +/// an object owned by the callback. +/// template internal::OwnedRefWrapper> OwnedRef(T&& t) { return internal::OwnedRefWrapper>(std::forward(t)); } -// Passed() is for transferring movable-but-not-copyable types (eg. unique_ptr) -// through a RepeatingCallback. Logically, this signifies a destructive transfer -// of the state of the argument into the target function. Invoking -// RepeatingCallback::Run() twice on a callback that was created with a Passed() -// argument will CHECK() because the first invocation would have already -// transferred ownership to the target function. -// -// Note that Passed() is not necessary with BindOnce(), as std::move() does the -// same thing. Avoid Passed() in favor of std::move() with BindOnce(). -// -// EXAMPLE OF Passed(): -// -// void TakesOwnership(std::unique_ptr arg) { } -// std::unique_ptr CreateFoo() { return std::make_unique(); -// } -// -// auto f = std::make_unique(); -// -// // |cb| is given ownership of Foo(). |f| is now NULL. -// // You can use std::move(f) in place of &f, but it's more verbose. -// RepeatingClosure cb = BindRepeating(&TakesOwnership, Passed(&f)); -// -// // Run was never called so |cb| still owns Foo() and deletes -// // it on Reset(). -// cb.Reset(); -// -// // |cb| is given a new Foo created by CreateFoo(). -// cb = BindRepeating(&TakesOwnership, Passed(CreateFoo())); -// -// // |arg| in TakesOwnership() is given ownership of Foo(). |cb| -// // no longer owns Foo() and, if reset, would not delete Foo(). -// cb.Run(); // Foo() is now transferred to |arg| and deleted. -// cb.Run(); // This CHECK()s since Foo() already been used once. -// -// We offer 2 syntaxes for calling Passed(). The first takes an rvalue and is -// best suited for use with the return value of a function or other temporary -// rvalues. The second takes a pointer to the scoper and is just syntactic sugar -// to avoid having to write Passed(std::move(scoper)). -// -// Both versions of Passed() prevent T from being an lvalue reference. The first -// via use of enable_if, and the second takes a T* which will not bind to T&. +/// +/// Passed() is for transferring movable-but-not-copyable types (eg. unique_ptr) +/// through a RepeatingCallback. Logically, this signifies a destructive +/// transfer of the state of the argument into the target function. Invoking +/// RepeatingCallback::Run() twice on a callback that was created with a +/// Passed() argument will CHECK() because the first invocation would have +/// already transferred ownership to the target function. +/// +/// Note that Passed() is not necessary with BindOnce(), as std::move() does the +/// same thing. Avoid Passed() in favor of std::move() with BindOnce(). +/// +/// EXAMPLE OF Passed(): +/// +/// 
+///   void TakesOwnership(std::unique_ptr arg) { }
+///   std::unique_ptr CreateFoo() { return std::make_unique();
+///   }
+///
+///   auto f = std::make_unique();
+///
+///   // |cb| is given ownership of Foo(). |f| is now NULL.
+///   // You can use std::move(f) in place of &f, but it's more verbose.
+///   RepeatingClosure cb = BindRepeating(&TakesOwnership, Passed(&f));
+///
+///   // Run was never called so |cb| still owns Foo() and deletes
+///   // it on Reset().
+///   cb.Reset();
+///
+///   // |cb| is given a new Foo created by CreateFoo().
+///   cb = BindRepeating(&TakesOwnership, Passed(CreateFoo()));
+///
+///   // |arg| in TakesOwnership() is given ownership of Foo(). |cb|
+///   // no longer owns Foo() and, if reset, would not delete Foo().
+///   cb.Run();  // Foo() is now transferred to |arg| and deleted.
+///   cb.Run();  // This CHECK()s since Foo() already been used once.
+///
+/// +/// We offer 2 syntaxes for calling Passed(). The first takes an rvalue and is +/// best suited for use with the return value of a function or other temporary +/// rvalues. The second takes a pointer to the scoper and is just syntactic +/// sugar to avoid having to write Passed(std::move(scoper)). +/// +/// Both versions of Passed() prevent T from being an lvalue reference. The +/// first via use of enable_if, and the second takes a T* which will not bind to +/// T&. +/// template ::value>* = nullptr> inline internal::PassedWrapper Passed(T&& scoper) { @@ -305,21 +337,25 @@ inline internal::PassedWrapper Passed(T* scoper) { return internal::PassedWrapper(std::move(*scoper)); } -// IgnoreResult() is used to adapt a function or callback with a return type to -// one with a void return. This is most useful if you have a function with, -// say, a pesky ignorable bool return that you want to use with PostTask or -// something else that expect a callback with a void return. -// -// EXAMPLE OF IgnoreResult(): -// -// int DoSomething(int arg) { cout << arg << endl; } -// -// // Assign to a callback with a void return type. -// OnceCallback cb = BindOnce(IgnoreResult(&DoSomething)); -// std::move(cb).Run(1); // Prints "1". -// -// // Prints "2" on |ml|. -// ml->PostTask(FROM_HERE, BindOnce(IgnoreResult(&DoSomething), 2); +/// +/// IgnoreResult() is used to adapt a function or callback with a return type to +/// one with a void return. This is most useful if you have a function with, +/// say, a pesky ignorable bool return that you want to use with PostTask or +/// something else that expect a callback with a void return. +/// +/// EXAMPLE OF IgnoreResult(): +/// +/// 
+///   int DoSomething(int arg) { cout << arg << endl; }
+///
+///   // Assign to a callback with a void return type.
+///   OnceCallback cb = BindOnce(IgnoreResult(&DoSomething));
+///   std::move(cb).Run(1);  // Prints "1".
+///
+///   // Prints "2" on |ml|.
+///   ml->PostTask(FROM_HERE, BindOnce(IgnoreResult(&DoSomething), 2);
+///
+/// template inline internal::IgnoreResultHelper IgnoreResult(T data) { return internal::IgnoreResultHelper(std::move(data)); @@ -327,16 +363,20 @@ inline internal::IgnoreResultHelper IgnoreResult(T data) { #if defined(OS_APPLE) && !HAS_FEATURE(objc_arc) -// RetainBlock() is used to adapt an Objective-C block when Automated Reference -// Counting (ARC) is disabled. This is unnecessary when ARC is enabled, as the -// BindOnce and BindRepeating already support blocks then. -// -// EXAMPLE OF RetainBlock(): -// -// // Wrap the block and bind it to a callback. -// OnceCallback cb = -// BindOnce(RetainBlock(^(int n) { NSLog(@"%d", n); })); -// std::move(cb).Run(1); // Logs "1". +/// +/// RetainBlock() is used to adapt an Objective-C block when Automated Reference +/// Counting (ARC) is disabled. This is unnecessary when ARC is enabled, as the +/// BindOnce and BindRepeating already support blocks then. +/// +/// EXAMPLE OF RetainBlock(): +/// +/// 
+///   // Wrap the block and bind it to a callback.
+///   OnceCallback cb =
+///       BindOnce(RetainBlock(^(int n) { NSLog(@"%d", n); }));
+///   std::move(cb).Run(1);  // Logs "1".
+///
+/// template base::mac::ScopedBlock RetainBlock(R (^block)(Args...)) { return base::mac::ScopedBlock(block, diff --git a/include/base/cef_build.h b/include/base/cef_build.h index 576056c89..48a088cb9 100644 --- a/include/base/cef_build.h +++ b/include/base/cef_build.h @@ -27,36 +27,40 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// This file adds defines about the platform we're currently building on. -// -// Operating System: -// OS_AIX / OS_ANDROID / OS_ASMJS / OS_FREEBSD / OS_FUCHSIA / OS_IOS / -// OS_LINUX / OS_MAC / OS_NACL (SFI or NONSFI) / OS_NETBSD / OS_OPENBSD / -// OS_QNX / OS_SOLARIS / OS_WIN -// Operating System family: -// OS_APPLE: IOS or MAC -// OS_BSD: FREEBSD or NETBSD or OPENBSD -// OS_POSIX: AIX or ANDROID or ASMJS or CHROMEOS or FREEBSD or IOS or LINUX -// or MAC or NACL or NETBSD or OPENBSD or QNX or SOLARIS -// -// /!\ Note: OS_CHROMEOS is set by the build system, not this file -// -// Compiler: -// COMPILER_MSVC / COMPILER_GCC -// -// Processor: -// ARCH_CPU_ARM64 / ARCH_CPU_ARMEL / ARCH_CPU_MIPS / ARCH_CPU_MIPS64 / -// ARCH_CPU_MIPS64EL / ARCH_CPU_MIPSEL / ARCH_CPU_PPC64 / ARCH_CPU_S390 / -// ARCH_CPU_S390X / ARCH_CPU_X86 / ARCH_CPU_X86_64 -// Processor family: -// ARCH_CPU_ARM_FAMILY: ARMEL or ARM64 -// ARCH_CPU_MIPS_FAMILY: MIPS64EL or MIPSEL or MIPS64 or MIPS -// ARCH_CPU_PPC64_FAMILY: PPC64 -// ARCH_CPU_S390_FAMILY: S390 or S390X -// ARCH_CPU_X86_FAMILY: X86 or X86_64 -// Processor features: -// ARCH_CPU_31_BITS / ARCH_CPU_32_BITS / ARCH_CPU_64_BITS -// ARCH_CPU_BIG_ENDIAN / ARCH_CPU_LITTLE_ENDIAN +/// \file +/// This file adds defines about the platform we're currently building on. +/// +/// 
+///  Operating System:
+///    OS_AIX / OS_ANDROID / OS_ASMJS / OS_FREEBSD / OS_FUCHSIA / OS_IOS /
+///    OS_LINUX / OS_MAC / OS_NACL (SFI or NONSFI) / OS_NETBSD / OS_OPENBSD /
+///    OS_QNX / OS_SOLARIS / OS_WIN
+///  Operating System family:
+///    OS_APPLE: IOS or MAC
+///    OS_BSD: FREEBSD or NETBSD or OPENBSD
+///    OS_POSIX: AIX or ANDROID or ASMJS or CHROMEOS or FREEBSD or IOS or LINUX
+///              or MAC or NACL or NETBSD or OPENBSD or QNX or SOLARIS
+///
+///  /!\ Note: OS_CHROMEOS is set by the build system, not this file
+///
+///  Compiler:
+///    COMPILER_MSVC / COMPILER_GCC
+///
+///  Processor:
+///    ARCH_CPU_ARM64 / ARCH_CPU_ARMEL / ARCH_CPU_MIPS / ARCH_CPU_MIPS64 /
+///    ARCH_CPU_MIPS64EL / ARCH_CPU_MIPSEL / ARCH_CPU_PPC64 / ARCH_CPU_S390 /
+///    ARCH_CPU_S390X / ARCH_CPU_X86 / ARCH_CPU_X86_64
+///  Processor family:
+///    ARCH_CPU_ARM_FAMILY: ARMEL or ARM64
+///    ARCH_CPU_MIPS_FAMILY: MIPS64EL or MIPSEL or MIPS64 or MIPS
+///    ARCH_CPU_PPC64_FAMILY: PPC64
+///    ARCH_CPU_S390_FAMILY: S390 or S390X
+///    ARCH_CPU_X86_FAMILY: X86 or X86_64
+///  Processor features:
+///    ARCH_CPU_31_BITS / ARCH_CPU_32_BITS / ARCH_CPU_64_BITS
+///    ARCH_CPU_BIG_ENDIAN / ARCH_CPU_LITTLE_ENDIAN
+///
+/// #ifndef CEF_INCLUDE_BASE_CEF_BUILD_H_ #define CEF_INCLUDE_BASE_CEF_BUILD_H_ diff --git a/include/base/cef_callback.h b/include/base/cef_callback.h index 4df8562b6..7034ff925 100644 --- a/include/base/cef_callback.h +++ b/include/base/cef_callback.h @@ -28,40 +28,38 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// ----------------------------------------------------------------------------- -// Usage documentation -// ----------------------------------------------------------------------------- -// -// Overview: -// A callback is similar in concept to a function pointer: it wraps a runnable -// object such as a function, method, lambda, or even another callback, allowing -// the runnable object to be invoked later via the callback object. -// -// Unlike function pointers, callbacks are created with base::BindOnce() or -// base::BindRepeating() and support partial function application. -// -// A base::OnceCallback may be Run() at most once; a base::RepeatingCallback may -// be Run() any number of times. |is_null()| is guaranteed to return true for a -// moved-from callback. -// -// // The lambda takes two arguments, but the first argument |x| is bound at -// // callback creation. -// base::OnceCallback cb = base::BindOnce([] (int x, int y) { -// return x + y; -// }, 1); -// // Run() only needs the remaining unbound argument |y|. -// printf("1 + 2 = %d\n", std::move(cb).Run(2)); // Prints 3 -// printf("cb is null? %s\n", -// cb.is_null() ? "true" : "false"); // Prints true -// std::move(cb).Run(2); // Crashes since |cb| has already run. -// -// Callbacks also support cancellation. A common use is binding the receiver -// object as a WeakPtr. If that weak pointer is invalidated, calling Run() -// will be a no-op. Note that |IsCancelled()| and |is_null()| are distinct: -// simply cancelling a callback will not also make it null. -// -// See https://chromium.googlesource.com/chromium/src/+/HEAD/docs/callback.md -// for the full documentation. +/// \file +/// A callback is similar in concept to a function pointer: it wraps a runnable +/// object such as a function, method, lambda, or even another callback, +/// allowing the runnable object to be invoked later via the callback object. +/// +/// Unlike function pointers, callbacks are created with base::BindOnce() or +/// base::BindRepeating() and support partial function application. +/// +/// A base::OnceCallback may be Run() at most once; a base::RepeatingCallback +/// may be Run() any number of times. |is_null()| is guaranteed to return true +/// for a moved-from callback. +/// +/// 
+///   // The lambda takes two arguments, but the first argument |x| is bound at
+///   // callback creation.
+///   base::OnceCallback cb = base::BindOnce([] (int x, int y) {
+///     return x + y;
+///   }, 1);
+///   // Run() only needs the remaining unbound argument |y|.
+///   printf("1 + 2 = %d\n", std::move(cb).Run(2));  // Prints 3
+///   printf("cb is null? %s\n",
+///          cb.is_null() ? "true" : "false");  // Prints true
+///   std::move(cb).Run(2);  // Crashes since |cb| has already run.
+///
+/// +/// Callbacks also support cancellation. A common use is binding the receiver +/// object as a WeakPtr. If that weak pointer is invalidated, calling Run() +/// will be a no-op. Note that |IsCancelled()| and |is_null()| are distinct: +/// simply cancelling a callback will not also make it null. +/// +/// See https://chromium.googlesource.com/chromium/src/+/lkgr/docs/callback.md +/// for the full documentation. #ifndef CEF_INCLUDE_BASE_CEF_CALLBACK_H_ #define CEF_INCLUDE_BASE_CEF_CALLBACK_H_ diff --git a/include/base/cef_callback_forward.h b/include/base/cef_callback_forward.h index 3587fa46f..863152fbb 100644 --- a/include/base/cef_callback_forward.h +++ b/include/base/cef_callback_forward.h @@ -48,9 +48,11 @@ class OnceCallback; template class RepeatingCallback; -// Syntactic sugar to make OnceClosure and RepeatingClosure -// easier to declare since they will be used in a lot of APIs with delayed -// execution. +/// +/// Syntactic sugar to make OnceClosure and RepeatingClosure +/// easier to declare since they will be used in a lot of APIs with delayed +/// execution. +/// using OnceClosure = OnceCallback; using RepeatingClosure = RepeatingCallback; diff --git a/include/base/cef_callback_helpers.h b/include/base/cef_callback_helpers.h index b5d775f62..bb572f707 100644 --- a/include/base/cef_callback_helpers.h +++ b/include/base/cef_callback_helpers.h @@ -75,24 +75,32 @@ struct IsOnceCallbackImpl> : std::true_type {}; } // namespace internal -// IsBaseCallback::value is true when T is any of the Closure or Callback -// family of types. +/// +/// IsBaseCallback::value is true when T is any of the Closure or Callback +/// family of types. +/// template using IsBaseCallback = internal::IsBaseCallbackImpl>; -// IsOnceCallback::value is true when T is a OnceClosure or OnceCallback -// type. +/// +/// IsOnceCallback::value is true when T is a OnceClosure or OnceCallback +/// type. +/// template using IsOnceCallback = internal::IsOnceCallbackImpl>; -// SFINAE friendly enabler allowing to overload methods for both Repeating and -// OnceCallbacks. -// -// Usage: -// template