Update documentation (#69)

* fix smart constructor docs

* update readme

* remove example

README.md

@@ -3,22 +3,15 @@
 
 A Haskell library for the [Chrome Devtools Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/), generated from the protocol's definition files.
 
-## Quick start
-
-`cdp` contains the generated library.
-
-To get started:
+## Example usage
 
-1. Clone the repo with submodules `git clone --recurse-submodules https://github.com/arsalan0c/cdp-hs.git`
-2. Switch directories to the CDP library: `cd cdp`
-3. Drop into nix environment: `nix-shell --pure`
-4. Generate cabal file: `hpack`
-5. Run Chromium with debugging port enabled: `chromium --headless --remote-debugging-port=9222 http://wikipedia.com`
-6. Run the example program to print the [browser's version info](https://chromedevtools.github.io/devtools-protocol/tot/Browser/#method-getVersion) : `cabal run cdp-exe`
+Ensure Chrome is running with the remote debugging port enabled:
 
-## Example usage
+```
+$ chromium --headless --remote-debugging-port=9222 https://wikipedia.com
+```
 
-Print a page to PDF, with Base64 encoded data being read in chunks:
+The following program can be used to print a page to PDF, with Base64 encoded data being read in chunks:
 
 ```hs
 {-# LANGUAGE OverloadedStrings   #-}
@@ -38,14 +31,12 @@ import qualified CDP as CDP
 main :: IO ()
 main = do
     let cfg = def
-    -- connect to a new page
-    id <- CDP.tiId <$> CDP.connectToTab cfg "https://haskell.foundation" 
-    CDP.runClient cfg (printPDF id)
+    CDP.runClient cfg printPDF
 
-printPDF :: T.Text -> CDP.Handle -> IO ()
-printPDF targetId handle = do
+printPDF :: CDP.Handle -> IO ()
+printPDF handle = do
     -- send the Page.printToPDF command
-    r <- CDP.sendCommandForSessionWait handle targetId $ CDP.pPagePrintToPDF
+    r <- CDP.sendCommandWait handle $ CDP.pPagePrintToPDF
         { CDP.pPagePrintToPDFTransferMode = Just CDP.PPagePrintToPDFTransferModeReturnAsStream
         }
 
@@ -75,10 +66,9 @@ whileTrue f act = do
 
 ## Generating the CDP library
 
-1. Build the generator library: `nix-build --attr exe`
-2. Run the generator: `result/bin/gen-exe`
-
-`cdp`, the library folder, will contain the newly generated code.
+```
+cabal run cdp-gen
+```
 
 ## Current state
 

examples/print-page.hs

@@ -15,14 +15,12 @@ import qualified CDP as CDP
 main :: IO ()
 main = do
     let cfg = def
-    -- connect to a new page
-    id <- CDP.tiId <$> CDP.connectToTab cfg "https://haskell.foundation" 
-    CDP.runClient cfg (printPDF id)
+    CDP.runClient cfg printPDF
 
-printPDF :: T.Text -> CDP.Handle -> IO ()
-printPDF targetId handle = do
+printPDF :: CDP.Handle -> IO ()
+printPDF handle = do
     -- send the Page.printToPDF command
-    r <- CDP.sendCommandForSessionWait handle targetId $ CDP.pPagePrintToPDF
+    r <- CDP.sendCommandWait handle $ CDP.pPagePrintToPDF
         { CDP.pPagePrintToPDFTransferMode = Just CDP.PPagePrintToPDFTransferModeReturnAsStream
         }
 

gen/CDP/Gen/Program.hs

@@ -187,8 +187,12 @@ genRecordSmartConstructor ctx domainName recName props =
     [conName] ++
     (indent $ do
         (isFirstParam, (mbDesc, ty)) <- markFirst types
-        formatDescription mbDesc ++
-            [ (if isFirstParam then ":: " else "-> ") <> ty ]) ++
+        let d1 = formatDescription mbDesc
+            d2 
+                | length d1 == 0 = d1
+                | otherwise      = "{-" : d1 ++ ["-}"]
+        d2 ++
+            [(if isFirstParam then ":: " else "-> ") <> ty]) ++
     [conName] ++
     indent args ++
     indent ["= " <> recName] ++

package.yaml

@@ -24,25 +24,25 @@ library:
     - gen
 
 dependencies:
-  - base
-  - aeson
-  - text
-  - bytestring
-  - containers
-  - data-default
-  - http-conduit
-  - mtl
-  - network-uri
-  - extra
-  - text
-  - vector
-  - websockets
-  - random
-  - monad-loops
-  - data-default
-  - process
-  - filepath
-  - directory
+  - base  ==4.14.3.0
+  - aeson ==1.5.6.0
+  - text  ==1.2.4.1
+  - bytestring ==0.10.12.0
+  - containers ==0.6.5.1
+  - data-default ==0.7.1.1
+  - http-conduit ==2.3.8
+  - mtl ==2.2.2
+  - network-uri ==2.6.4.1
+  - extra ==1.7.9
+  - text ==1.2.4.1
+  - vector ==0.12.3.1
+  - websockets ==0.12.7.3
+  - random ==1.2.0
+  - monad-loops ==0.4.3
+  - data-default ==0.7.1.1
+  - process ==1.6.13.2
+  - filepath ==1.4.2.1
+  - directory ==1.3.6.0
 
 executables:
   cdp-gen:
@@ -84,8 +84,7 @@ executables:
     main: sessions.hs
     dependencies:
       - cdp
-
-
+
 tests:
   cdp-test:
     source-dirs: test

src/CDP/Domains/Animation.hs

@@ -288,7 +288,9 @@ data PAnimationGetCurrentTime = PAnimationGetCurrentTime
   }
   deriving (Eq, Show)
 pAnimationGetCurrentTime
+  {-
   -- | Id of animation.
+  -}
   :: T.Text
   -> PAnimationGetCurrentTime
 pAnimationGetCurrentTime
@@ -346,7 +348,9 @@ data PAnimationReleaseAnimations = PAnimationReleaseAnimations
   }
   deriving (Eq, Show)
 pAnimationReleaseAnimations
+  {-
   -- | List of animation ids to seek.
+  -}
   :: [T.Text]
   -> PAnimationReleaseAnimations
 pAnimationReleaseAnimations
@@ -372,7 +376,9 @@ data PAnimationResolveAnimation = PAnimationResolveAnimation
   }
   deriving (Eq, Show)
 pAnimationResolveAnimation
+  {-
   -- | Animation id.
+  -}
   :: T.Text
   -> PAnimationResolveAnimation
 pAnimationResolveAnimation
@@ -408,9 +414,13 @@ data PAnimationSeekAnimations = PAnimationSeekAnimations
   }
   deriving (Eq, Show)
 pAnimationSeekAnimations
+  {-
   -- | List of animation ids to seek.
+  -}
   :: [T.Text]
+  {-
   -- | Set the current time of each animation.
+  -}
   -> Double
   -> PAnimationSeekAnimations
 pAnimationSeekAnimations
@@ -441,9 +451,13 @@ data PAnimationSetPaused = PAnimationSetPaused
   }
   deriving (Eq, Show)
 pAnimationSetPaused
+  {-
   -- | Animations to set the pause state of.
+  -}
   :: [T.Text]
+  {-
   -- | Paused state to set to.
+  -}
   -> Bool
   -> PAnimationSetPaused
 pAnimationSetPaused
@@ -472,7 +486,9 @@ data PAnimationSetPlaybackRate = PAnimationSetPlaybackRate
   }
   deriving (Eq, Show)
 pAnimationSetPlaybackRate
+  {-
   -- | Playback rate for animations on page
+  -}
   :: Double
   -> PAnimationSetPlaybackRate
 pAnimationSetPlaybackRate
@@ -502,11 +518,17 @@ data PAnimationSetTiming = PAnimationSetTiming
   }
   deriving (Eq, Show)
 pAnimationSetTiming
+  {-
   -- | Animation id.
+  -}
   :: T.Text
+  {-
   -- | Duration of the animation.
+  -}
   -> Double
+  {-
   -- | Delay of the animation.
+  -}
   -> Double
   -> PAnimationSetTiming
 pAnimationSetTiming

src/CDP/Domains/Audits.hs

@@ -1216,9 +1216,13 @@ data PAuditsGetEncodedResponse = PAuditsGetEncodedResponse
   }
   deriving (Eq, Show)
 pAuditsGetEncodedResponse
+  {-
   -- | Identifier of the network request to get content for.
+  -}
   :: DOMPageNetworkEmulationSecurity.NetworkRequestId
+  {-
   -- | The encoding to use.
+  -}
   -> PAuditsGetEncodedResponseEncoding
   -> PAuditsGetEncodedResponse
 pAuditsGetEncodedResponse

src/CDP/Domains/BrowserTarget.hs

@@ -352,9 +352,13 @@ data PBrowserSetPermission = PBrowserSetPermission
   }
   deriving (Eq, Show)
 pBrowserSetPermission
+  {-
   -- | Descriptor of permission to override.
+  -}
   :: BrowserPermissionDescriptor
+  {-
   -- | Setting of the permission.
+  -}
   -> BrowserPermissionSetting
   -> PBrowserSetPermission
 pBrowserSetPermission
@@ -466,9 +470,11 @@ data PBrowserSetDownloadBehavior = PBrowserSetDownloadBehavior
   }
   deriving (Eq, Show)
 pBrowserSetDownloadBehavior
+  {-
   -- | Whether to allow all or deny all download requests, or use default Chrome behavior if
   --   available (otherwise deny). |allowAndName| allows download and names files according to
   --   their dowmload guids.
+  -}
   :: PBrowserSetDownloadBehaviorBehavior
   -> PBrowserSetDownloadBehavior
 pBrowserSetDownloadBehavior
@@ -502,7 +508,9 @@ data PBrowserCancelDownload = PBrowserCancelDownload
   }
   deriving (Eq, Show)
 pBrowserCancelDownload
+  {-
   -- | Global unique identifier of the download.
+  -}
   :: T.Text
   -> PBrowserCancelDownload
 pBrowserCancelDownload
@@ -678,7 +686,9 @@ data PBrowserGetHistogram = PBrowserGetHistogram
   }
   deriving (Eq, Show)
 pBrowserGetHistogram
+  {-
   -- | Requested histogram name.
+  -}
   :: T.Text
   -> PBrowserGetHistogram
 pBrowserGetHistogram
@@ -714,7 +724,9 @@ data PBrowserGetWindowBounds = PBrowserGetWindowBounds
   }
   deriving (Eq, Show)
 pBrowserGetWindowBounds
+  {-
   -- | Browser window id.
+  -}
   :: BrowserWindowID
   -> PBrowserGetWindowBounds
 pBrowserGetWindowBounds
@@ -787,10 +799,14 @@ data PBrowserSetWindowBounds = PBrowserSetWindowBounds
   }
   deriving (Eq, Show)
 pBrowserSetWindowBounds
+  {-
   -- | Browser window id.
+  -}
   :: BrowserWindowID
+  {-
   -- | New window bounds. The 'minimized', 'maximized' and 'fullscreen' states cannot be combined
   --   with 'left', 'top', 'width' or 'height'. Leaves unspecified fields unchanged.
+  -}
   -> BrowserBounds
   -> PBrowserSetWindowBounds
 pBrowserSetWindowBounds
@@ -1296,7 +1312,9 @@ data PTargetCreateTarget = PTargetCreateTarget
   }
   deriving (Eq, Show)
 pTargetCreateTarget
+  {-
   -- | The initial URL the page will be navigated to. An empty string indicates about:blank.
+  -}
   :: T.Text
   -> PTargetCreateTarget
 pTargetCreateTarget
@@ -1465,10 +1483,14 @@ data PTargetSetAutoAttach = PTargetSetAutoAttach
   }
   deriving (Eq, Show)
 pTargetSetAutoAttach
+  {-
   -- | Whether to auto-attach to related targets.
+  -}
   :: Bool
+  {-
   -- | Whether to pause new targets when attaching to them. Use `Runtime.runIfWaitingForDebugger`
   --   to run paused targets.
+  -}
   -> Bool
   -> PTargetSetAutoAttach
 pTargetSetAutoAttach
@@ -1510,8 +1532,10 @@ data PTargetAutoAttachRelated = PTargetAutoAttachRelated
   deriving (Eq, Show)
 pTargetAutoAttachRelated
   :: TargetTargetID
+  {-
   -- | Whether to pause new targets when attaching to them. Use `Runtime.runIfWaitingForDebugger`
   --   to run paused targets.
+  -}
   -> Bool
   -> PTargetAutoAttachRelated
 pTargetAutoAttachRelated
@@ -1546,7 +1570,9 @@ data PTargetSetDiscoverTargets = PTargetSetDiscoverTargets
   }
   deriving (Eq, Show)
 pTargetSetDiscoverTargets
+  {-
   -- | Whether to discover available targets.
+  -}
   :: Bool
   -> PTargetSetDiscoverTargets
 pTargetSetDiscoverTargets
@@ -1575,7 +1601,9 @@ data PTargetSetRemoteLocations = PTargetSetRemoteLocations
   }
   deriving (Eq, Show)
 pTargetSetRemoteLocations
+  {-
   -- | List of remote locations.
+  -}
   :: [TargetRemoteLocation]
   -> PTargetSetRemoteLocations
 pTargetSetRemoteLocations