From 59922a31b00a420b3a28195ce8cbf45c84e6243a Mon Sep 17 00:00:00 2001
From: Dana Jansens <danakj@chromium.org>
Date: Sun, 24 Dec 2023 22:07:11 -0500
Subject: [PATCH] Document the construct namespace

---
 sus/CMakeLists.txt        |  1 +
 sus/construct/construct.h | 42 +++++++++++++++++++++++++++++++++++++++
 sus/construct/from.h      |  1 +
 3 files changed, 44 insertions(+)
 create mode 100644 sus/construct/construct.h

diff --git a/sus/CMakeLists.txt b/sus/CMakeLists.txt
index f3b6e584f..c52d372d3 100644
--- a/sus/CMakeLists.txt
+++ b/sus/CMakeLists.txt
@@ -41,6 +41,7 @@ target_sources(subspace PUBLIC
     "cmp/ord.h"
     "cmp/reverse.h"
     "construct/__private/into_ref.h"
+    "construct/construct.h"
     "construct/from.h"
     "construct/into.h"
     "construct/default.h"
diff --git a/sus/construct/construct.h b/sus/construct/construct.h
new file mode 100644
index 000000000..ce384c463
--- /dev/null
+++ b/sus/construct/construct.h
@@ -0,0 +1,42 @@
+// Copyright 2023 Google LLC
+//
+// 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
+//
+//     https://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.
+
+#pragma once
+
+namespace sus {
+
+/// Concepts and functions for constructing and converting between types.
+///
+/// The [`cast`]($sus::construct::cast) function is built on the
+/// [`Cast`]($sus::construct::Cast) concept to convert between numeric and
+/// primitive types in a safer way than `static_cast`.
+///
+/// The [`From`]($sus::construct::From) and [`Into`]($sus::construct::Into)
+/// concepts allow converting in a lossless and infallible way between types,
+/// and accepting generics that can convert to a desired type. The
+/// [`into`]($sus::construct::into) function allows explicit conversion while
+/// deducing the target type, such as for converting function arguments or
+/// return values.
+///
+/// The [`Default`]($sus::construct::Default) concept matches types which can be
+/// default constructed, allowing their use in generic code.
+///
+/// The [`SafelyConstructibleFromReference`](
+/// $sus::construct::SafelyConstructibleFromReference) concept pairs with the
+/// `[[clang::lifetimebound]]` attribute, which gives better protection with
+/// Clang. The concept can be used in generic code that accepts reference types
+/// to prevent receiving references to implicit temporary objects in a
+/// standard way.
+namespace construct {}
+}
diff --git a/sus/construct/from.h b/sus/construct/from.h
index 8d818f5d6..26d2a249f 100644
--- a/sus/construct/from.h
+++ b/sus/construct/from.h
@@ -16,6 +16,7 @@
 
 #include <concepts>
 
+#include "sus/construct/construct.h"
 #include "sus/mem/forward.h"
 #include "sus/result/__private/is_result_type.h"