From c1e5a64a0c5c992f33d650a24c57ff63b6844052 Mon Sep 17 00:00:00 2001
From: Simon Krueger <skrueger@meta.com>
Date: Thu, 5 Dec 2024 16:31:58 -0800
Subject: [PATCH] Update TestMain fbcref doc comments

Summary:
Updates TestMain's doc comments so it appears on the fbcref website.

Also include a demo doc file on how to use it.

Reviewed By: Gownta

Differential Revision: D66765229

fbshipit-source-id: affd6f0321e3251e2a7ec83cfb9bf6ed55649faa
---
 .../folly/test/common/TestMainDemo.cpp        | 38 +++++++++++++++++++
 .../folly/src/folly/test/common/TestMain.cpp  |  6 ++-
 2 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 third-party/folly/src/folly/docs/examples/folly/test/common/TestMainDemo.cpp

diff --git a/third-party/folly/src/folly/docs/examples/folly/test/common/TestMainDemo.cpp b/third-party/folly/src/folly/docs/examples/folly/test/common/TestMainDemo.cpp
new file mode 100644
index 00000000000000..ecc9bd0c0dc94f
--- /dev/null
+++ b/third-party/folly/src/folly/docs/examples/folly/test/common/TestMainDemo.cpp
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This file demonstrates the usage of folly/test/common:test_main_lib,
+ * which is a `main` implementation that initializes gtest & folly before
+ * running tests.
+ * @file
+ */
+
+#include <folly/Singleton.h>
+
+#include <gtest/gtest.h>
+
+using namespace ::testing;
+
+namespace {
+/// This is a singleton that demonstrates folly will be initialized by
+/// `//folly/test/common:test_main_lib`.
+folly::Singleton<int> DemoSingleton([]() { return new int(42); });
+} // namespace
+
+TEST(TestMainDemo, SingletonAccess) {
+  ASSERT_EQ(*DemoSingleton.try_get(), 42);
+}
diff --git a/third-party/folly/src/folly/test/common/TestMain.cpp b/third-party/folly/src/folly/test/common/TestMain.cpp
index e8daf8b39e1e42..fbe273a1b15edf 100644
--- a/third-party/folly/src/folly/test/common/TestMain.cpp
+++ b/third-party/folly/src/folly/test/common/TestMain.cpp
@@ -21,10 +21,14 @@
 #include <folly/portability/GFlags.h>
 #include <folly/portability/GTest.h>
 
-/*
+/**
  * This is the recommended main function for all tests.
+ * Before running all the tests, it initializes GoogleTest and folly.
+ * By default, this configures Google Logging (glog) to output to stderr.
+ *
  * The Makefile links it into all of the test programs so that tests do not need
  * to - and indeed should typically not - define their own main() functions
+ * @file
  */
 FOLLY_ATTR_WEAK int main(int argc, char** argv);