From c3a517cb4f7efd89a031f134dab43b4f3d85217b Mon Sep 17 00:00:00 2001
From: Philip Patsch <philip.patsch@tweag.io>
Date: Wed, 3 Feb 2021 07:52:28 +0100
Subject: [PATCH] doc(servant-foreign): Inflection docs & module docs

---
 servant-foreign/src/Servant/Foreign.hs        |  2 ++
 .../src/Servant/Foreign/Inflections.hs        | 30 +++++++++++--------
 .../src/Servant/Foreign/Internal.hs           |  5 ++--
 3 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/servant-foreign/src/Servant/Foreign.hs b/servant-foreign/src/Servant/Foreign.hs
index aa1a5573..1df5bf74 100644
--- a/servant-foreign/src/Servant/Foreign.hs
+++ b/servant-foreign/src/Servant/Foreign.hs
@@ -1,5 +1,7 @@
 -- | Generalizes all the data needed to make code generation work with
 -- arbitrary programming languages.
+--
+-- See documentation of 'HasForeignType' for a simple example. 'listFromAPI' returns a list of all your endpoints and their foreign types, given a mapping from Haskell types to foreign types (conventionally called `ftypes` below).
 module Servant.Foreign
   ( ArgType(..)
   , HeaderArg(..)
diff --git a/servant-foreign/src/Servant/Foreign/Inflections.hs b/servant-foreign/src/Servant/Foreign/Inflections.hs
index 793ea36d..42f89927 100644
--- a/servant-foreign/src/Servant/Foreign/Inflections.hs
+++ b/servant-foreign/src/Servant/Foreign/Inflections.hs
@@ -20,20 +20,31 @@ import           Prelude                  hiding
                  (head, tail)
 import           Servant.Foreign.Internal
 
+-- | Simply concat each part of the FunctionName together.
+--
+-- @[ "get", "documents", "by", "id" ] → "getdocumentsbyid"@
+concatCase :: FunctionName -> Text
+concatCase = view concatCaseL
+
 concatCaseL :: Getter FunctionName Text
 concatCaseL = _FunctionName . to mconcat
 
--- | Function name builder that simply concat each part together
-concatCase :: FunctionName -> Text
-concatCase = view concatCaseL
+-- | Use the snake_case convention.
+-- Each part is separated by a single underscore character.
+--
+-- @[ "get", "documents", "by", "id" ] → "get_documents_by_id"@
+snakeCase :: FunctionName -> Text
+snakeCase = view snakeCaseL
 
 snakeCaseL :: Getter FunctionName Text
 snakeCaseL = _FunctionName . to (intercalate "_")
 
--- | Function name builder using the snake_case convention.
--- each part is separated by a single underscore character.
-snakeCase :: FunctionName -> Text
-snakeCase = view snakeCaseL
+-- | Use the camelCase convention.
+-- The first part is lower case, every other part starts with an upper case character.
+--
+-- @[ "get", "documents", "by", "id" ] → "getDocumentsById"@
+camelCase :: FunctionName -> Text
+camelCase = view camelCaseL
 
 camelCaseL :: Getter FunctionName Text
 camelCaseL = _FunctionName . to convert
@@ -42,8 +53,3 @@ camelCaseL = _FunctionName . to convert
     convert (p:ps) = mconcat $ p : map capitalize ps
     capitalize ""   = ""
     capitalize name = C.toUpper (head name) `cons` tail name
-
--- | Function name builder using the CamelCase convention.
--- each part begins with an upper case character.
-camelCase :: FunctionName -> Text
-camelCase = view camelCaseL
diff --git a/servant-foreign/src/Servant/Foreign/Internal.hs b/servant-foreign/src/Servant/Foreign/Internal.hs
index 22f37ad9..5c82c056 100644
--- a/servant-foreign/src/Servant/Foreign/Internal.hs
+++ b/servant-foreign/src/Servant/Foreign/Internal.hs
@@ -13,8 +13,6 @@
 {-# LANGUAGE TypeOperators              #-}
 {-# LANGUAGE UndecidableInstances       #-}
 
--- | Generalizes all the data needed to make code generation work with
--- arbitrary programming languages.
 module Servant.Foreign.Internal where
 
 import           Prelude ()
@@ -40,6 +38,9 @@ import           Servant.API.Modifiers
                  (RequiredArgument)
 import           Servant.API.TypeLevel
 
+-- | Canonical name of the endpoint, can be used to generate a function name.
+--
+-- You can use the functions in "Servant.Foreign.Inflections", like 'Servant.Foreign.Inflections.camelCase' to transform to `Text`.
 newtype FunctionName = FunctionName { unFunctionName :: [Text] }
   deriving (Data, Show, Eq, Semigroup, Monoid, Typeable)