From 077280d7f6295441df3072810ed390ba8eae8696 Mon Sep 17 00:00:00 2001
From: Justin Ethier <justin.ethier@gmail.com>
Date: Mon, 8 Jun 2020 17:52:01 -0400
Subject: [PATCH] Added docs for (cyclone foreign)

---
 docs/API.md                 |  1 +
 docs/api/cyclone/foreign.md | 77 +++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 docs/api/cyclone/foreign.md

diff --git a/docs/API.md b/docs/API.md
index 734bd705..f8684ba9 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -61,6 +61,7 @@ Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http:
 These libraries are provided by Cyclone with a stable API that is unlikely to change:
 
 - [`cyclone concurrent`](api/cyclone/concurrent) - A helper library for writing concurrent code.
+- [`cyclone foreign`](api/cyclone/foreign) - Provides a convenient interface for integrating with C code.
 - [`cyclone match`](api/cyclone/match) - A hygienic pattern matcher based on Alex Shinn's portable `match.scm`.
 - [`cyclone test`](api/cyclone/test) - A unit testing framework ported from `(chibi test)`.
 - [`scheme cyclone pretty-print`](api/scheme/cyclone/pretty-print) - A pretty printer.
diff --git a/docs/api/cyclone/foreign.md b/docs/api/cyclone/foreign.md
new file mode 100644
index 00000000..694e8c3f
--- /dev/null
+++ b/docs/api/cyclone/foreign.md
@@ -0,0 +1,77 @@
+---
+layout: main
+title: API
+---
+
+# Foreign Library
+
+The `(cyclone foreign)` provides a convenient interface for integrating with C code. It is based in concept on the `(chicken foreign)` module from CHICKEN Scheme. Similarly to that module, this library manipulates the C code directly before it is compiled to a native binary. It is not possible to call these forms at runtime.
+
+# Overview
+
+- [`c-code`](#c-code)
+- [`c-value`](#c-value)
+- [`c-define`](#c-define)
+- [`c-define-type`](#c-define-type)
+
+## c-code
+
+*Syntax*
+
+    (c-code CODE ...)
+
+Insert C code directly into the compiled program. Each `CODE` parameter must be a string containing C code.
+
+## c-value
+
+*Syntax*
+
+    (c-value CODE TYPE)
+
+Generate code that takes the C code specified by the string `CODE` and converts it to a Scheme object of type `TYPE`.
+
+## c-define
+
+*Syntax*
+
+    (c-define SCM-FUNC RETURN-TYPE C-FUNC TYPE ...)
+
+Define a Scheme function `SCM-FUNC` returning an object of type `RETURN-TYPE`. The function will call C function specified by the string `C-FUNC` passed parameters of type specified by any `TYPE` arguments.
+
+For example, to define a function that calls `strlen`:
+
+    (c-define scm-strlen int "strlen" string)
+
+Note that these definitions are introduced at the top-level.
+
+## c-define-type
+
+*Syntax*
+
+    (c-define-type NAME TYPE (ARG-CONVERT (RET-CONVERT)))
+
+Define a custom type with symbol `NAME` that is an alias of type `TYPE`. It is also possible to specify conversion functions `ARG-CONVERT` and `RET-CONVERT` to convert to/from this custom type.
+
+EG, to define a type that consists of integers in Scheme and strings in C: 
+
+    (c-define-type string-as-integer string number->string string->number)
+
+
+# Type Specifiers
+
+The following built-in specifiers may be used as a `TYPE` for forms in this module. 
+
+Scheme | C
+------ | -
+`int` | `int`
+`integer` | `int`
+`bool` | `int`
+`char` | `int`
+`string` | `char *`
+`symbol` | `const char *`
+`bytevector` | `char *`
+`float` | `double`
+`double` | `double`
+`bignum` | `mp_int`
+`opaque` | `void *`
+