Documentation (#1086)

Add documentation for #1071.

include/gsl/assert

@@ -14,8 +14,8 @@
 //
 ///////////////////////////////////////////////////////////////////////////////
 
-#ifndef GSL_CONTRACTS_H
-#define GSL_CONTRACTS_H
+#ifndef GSL_ASSERT_H
+#define GSL_ASSERT_H
 
 //
 // Temporary until MSVC STL supports no-exceptions mode.
@@ -133,4 +133,4 @@ namespace details
 #pragma clang diagnostic pop
 #endif
 
-#endif // GSL_CONTRACTS_H
+#endif // GSL_ASSERT_H

include/gsl/pointers

@@ -68,8 +68,9 @@ using std::unique_ptr;
 //
 // owner
 //
-// owner<T> is designed as a bridge for code that must deal directly with owning pointers for some
-// reason
+// `gsl::owner<T>` is designed as a safety mechanism for code that must deal directly with raw pointers that own memory.
+// Ideally such code should be restricted to the implementation of low-level abstractions. `gsl::owner` can also be used
+// as a stepping point in converting legacy code to use more modern RAII constructs, such as smart pointers.
 //
 // T must be a pointer type
 // - disallow construction from any type other than pointer type