From 865068322c01480f388b0deb43e0b7e15746d543 Mon Sep 17 00:00:00 2001
From: Tim Condon <0xTim@users.noreply.github.com>
Date: Thu, 12 Dec 2024 16:38:42 +0000
Subject: [PATCH] Add Intial DocC docs (#283)

Adds some additional documentation. I don't know how far you want me to
go with documenting everything so let me know. This should at least get
the current APIs rendered on SPI. As an aside I'm not a huge fan of
linking out to the CryptoKit docs since not everything is available
here, all the code is already documented here and most of the tutorials
and articles on developer.apple.com for CryptoKit refer to Apple
Platform specific stuff, like interacting with the keychain, that is not
applicable here.

Resolves #273

### Checklist
- [x] I've run tests to see all new and existing tests pass
- [x] I've followed the code style of the rest of the project
- [x] I've read the [Contribution Guidelines](CONTRIBUTING.md)
- [x] I've updated the documentation if necessary

#### If you've made changes to `gyb` files
- [x] I've run `.script/generate_boilerplate_files_with_gyb` and
included updated generated files in a commit of this pull request

### Motivation:

Currently Swift Crypto has no documentation which is not great

### Modifications:

Adds additional DocC scaffolding to take advantage of the DocC comments
in Crypto and CryptoExtras. Adds an SPI config file for Swift Package
Index

### Result:

We will have some documentation
---
 .spi.yml                                 |  2 +-
 Sources/Crypto/Docs.docc/index.md        | 12 ++++++++++++
 Sources/_CryptoExtras/Docs.docc/index.md |  5 +++++
 3 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 Sources/Crypto/Docs.docc/index.md
 create mode 100644 Sources/_CryptoExtras/Docs.docc/index.md

diff --git a/.spi.yml b/.spi.yml
index f84c610c..f07df006 100644
--- a/.spi.yml
+++ b/.spi.yml
@@ -1,4 +1,4 @@
 version: 1
 builder:
   configs:
-    - documentation_targets: [Crypto]
+    - documentation_targets: [Crypto, _CryptoExtras]
diff --git a/Sources/Crypto/Docs.docc/index.md b/Sources/Crypto/Docs.docc/index.md
new file mode 100644
index 00000000..e44b543b
--- /dev/null
+++ b/Sources/Crypto/Docs.docc/index.md
@@ -0,0 +1,12 @@
+# ``Crypto``
+
+A cryptography library for Swift.
+
+## Overview
+
+Swift Crypto provides a Swift library for common cryptographic operations. It is available as a Swift package and provides two main libraries:
+
+* `Crypto` - an open-source implementation of a substantial portion of the API of [Apple CryptoKit](https://developer.apple.com/documentation/cryptokit) suitable for use on Linux platforms. It enables cross-platform or server applications with the advantages of CryptoKit.
+* `CryptoExtras` - a collection of additional cryptographic primitives and utilities that are not part of CryptoKit but useful in a server environment.
+
+Swift Crypto is built on top of [BoringSSL](https://boringssl.googlesource.com/boringssl/), Google's fork of OpenSSL. The current features of Swift Crypto cover key exchange, key derivation, encryption and decryption, hashing, message authentication, and more.
\ No newline at end of file
diff --git a/Sources/_CryptoExtras/Docs.docc/index.md b/Sources/_CryptoExtras/Docs.docc/index.md
new file mode 100644
index 00000000..310cf0dd
--- /dev/null
+++ b/Sources/_CryptoExtras/Docs.docc/index.md
@@ -0,0 +1,5 @@
+# ``CryptoExtras``
+
+Provides additional cryptographic APIs that are not available in CryptoKit (and therefore the core Crypto library).
+
+