@@ -177,10 +177,11 @@
177177--
178178-- [First Example: Echo]
179179--
180−-- The @echo@ demo starts a new Cloud Haskell node, waits for input from the
181−-- user on the local machine, sends this to the remote machine. The remote
182−-- machine will echo this back; the local machine will wait for the echo, show
183−-- the echo, and repeat.
180+-- When we run the @cloud-haskell-azure-echo@ demo on our local machine, it
181+-- starts a new Cloud Haskell node on the specified remote virtual machine. It
182+-- then repeatedly waits for input from the user on the local machine, sends
183+-- this to the remote virtual machine which will echo it back, and wait for and
184+-- show the echo.
184185--
185186-- Before you can try it you will first need to copy the executable (for
186187-- example, using scp, although the Azure backend also provides this natively
@@ -233,16 +234,35 @@
233234-- > main = do
234235-- > args <- getArgs
235236-- > case args of
236−-- > "onvm":args' -> onVmMain __remoteTable args'
237+-- > "onvm":args' ->
238+-- > -- Pass execution to 'onVmMain' if we are running on the VM
239+-- > -- ('callOnVM' will provide the right arguments)
240+-- > onVmMain __remoteTable args'
241+-- >
237242-- > sid:x509:pkey:user:cloudService:virtualMachine:port:_ -> do
243+-- > -- Initialize the Azure backend
238244-- > params <- defaultAzureParameters sid x509 pkey
239245-- > let params' = params { azureSshUserName = user }
240246-- > backend <- initializeBackend params' cloudService
247+-- >
248+-- > -- Find the specified virtual machine
241249-- > Just vm <- findNamedVM backend virtualMachine
250+-- >
251+-- > -- Run the echo client proper
242252-- > callOnVM backend vm port $
243253-- > ProcessPair ($(mkClosure 'echoRemote) ())
244254-- > echoLocal
245255--
256+-- The most important part of this code is the last three lines
257+--
258+-- > callOnVM backend vm port $
259+-- > ProcessPair ($(mkClosure 'echoRemote) ())
260+-- > echoLocal
261+--
262+-- 'callOnVM' creats a new Cloud Haskell node on the specified virtual machine,
263+-- then runs @echoRemote@ on the remote machine and @echoLocal@ on the local
264+-- machine.
265+--
246266-- [Second Example: Ping]
247267--
248268-- The second example differs from the @echo@ demo in that it uses both
@@ -263,7 +283,13 @@
263283-- > <<virtual machine name>> \
264284-- > <<port number>>
265285--
266−-- Finally, we can run the ping client:
286+-- As before, when we execute this on our local machine, it starts a new Cloud
287+-- Haskell node on the specified remote virtual machine and then executes the
288+-- ping server. Unlike with the echo example, however, this command will
289+-- terminate once the Cloud Haskell node has been set up, leaving the ping
290+-- server running in the background.
291+--
292+-- Once the ping server is running we can run the ping client:
267293--
268294-- > cloud-haskell-azure-ping client \
269295-- > <<subscription ID>> \
@@ -339,16 +365,26 @@
339365-- > main = do
340366-- > args <- getArgs
341367-- > case args of
342−-- > "onvm":args' -> onVmMain __remoteTable args'
368+-- > "onvm":args' ->
369+-- > -- Pass execution to 'onVmMain' if we are running on the VM
370+-- > onVmMain __remoteTable args'
371+-- >
343372-- > "list":sid:x509:pkey:_ -> do
373+-- > -- List all available cloud services
374+-- > -- (useful, but not strictly necessary for the example)
344375-- > params <- defaultAzureParameters sid x509 pkey
345376-- > css <- cloudServices (azureSetup params)
346377-- > mapM_ print css
378+-- >
347379-- > cmd:sid:x509:pkey:user:cloudService:virtualMachine:port:_ -> do
380+-- > -- Initialize the backend and find the right VM
348381-- > params <- defaultAzureParameters sid x509 pkey
349382-- > let params' = params { azureSshUserName = user }
350383-- > backend <- initializeBackend params' cloudService
351384-- > Just vm <- findNamedVM backend virtualMachine
385+-- >
386+-- > -- The same binary can behave as the client or the server,
387+-- > -- depending on the command line arguments
352388-- > case cmd of
353389-- > "server" -> spawnOnVM backend vm port ($(mkClosure 'pingServer) ())
354390-- > "client" -> callOnVM backend vm port $