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/docs/examples/folly/test/common/BUCK

@@ -0,0 +1,12 @@
+load("@fbcode_macros//build_defs:cpp_unittest.bzl", "cpp_unittest")
+
+oncall("fbcode_entropy_wardens_folly")
+
+cpp_unittest(
+    name = "test_main_demo",
+    srcs = ["TestMainDemo.cpp"],
+    test_main = "//folly/test/common:test_main_lib",
+    deps = [
+        "//folly:singleton",
+    ],
+)

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);
+}

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);