From 636960787e288a4919daa51a436157fdb580bc36 Mon Sep 17 00:00:00 2001
From: Antoine Leblanc <antoine@hasura.io>
Date: Fri, 24 Sep 2021 18:01:40 +0100
Subject: [PATCH] Fix haddock generation and introduce PR check

On `main`, currently, haddock generation is broken, due to some unrecognized comments. This PR fixes this, and changes our `build_oss_server` CI job to ensure that future PRs do not break haddock.

https://github.com/hasura/graphql-engine-mono/pull/2222

GitOrigin-RevId: 909bbcdc7b2d31c9a3e947ce6b7691e23f59b916
---
 server/Makefile                               |  8 +++++++
 .../Hasura/GraphQL/Transport/WebSocket.hs     | 22 +++++++++++--------
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/server/Makefile b/server/Makefile
index e25bb2d8ffe..b0c59c22727 100644
--- a/server/Makefile
+++ b/server/Makefile
@@ -9,6 +9,7 @@ registry := hasura
 packager_ver := 20210218
 pg_dump_ver := 13
 build_output := /build/_server_output
+docs_output := /build/_docs_output.tar.gz
 
 # Getting access to the built products with the `cabal v2-*` commands is really awkward; see
 # <https://www.haskell.org/cabal/users-guide/nix-local-build.html#where-are-my-build-products> for a
@@ -31,6 +32,13 @@ ci-build:
 	echo '$(VERSION)' > '$(build_output)/version.txt'
 	shopt -s failglob globstar && cp $(executables_glob) '$(build_output)/'
 
+# assumes this is built in circleci
+ci-docs:
+	# build
+	cabal haddock
+	# copy
+	cd ../dist-newstyle/build/*/*/graphql-engine-*/**/doc/html/graphql-engine/ && tar czf $(docs_output) *
+
 # assumes this is built in circleci
 ci-image:
 	mkdir -p packaging/build/rootfs
diff --git a/server/src-lib/Hasura/GraphQL/Transport/WebSocket.hs b/server/src-lib/Hasura/GraphQL/Transport/WebSocket.hs
index f787742cd34..9b81d040474 100644
--- a/server/src-lib/Hasura/GraphQL/Transport/WebSocket.hs
+++ b/server/src-lib/Hasura/GraphQL/Transport/WebSocket.hs
@@ -1,20 +1,24 @@
--- | This file contains the handlers that are used within websocket server
+{-# LANGUAGE CPP #-}
+
+-- | This file contains the handlers that are used within websocket server.
+--
+-- This module export three main handlers for the websocket server ('onConn',
+-- 'onMessage', 'onClose'), and two helpers for sending messages to the client
+-- ('sendMsg', 'sendCloseWithMsg').
+--
+-- NOTE!
+--  The handler functions 'onClose', 'onMessage', etc. depend for correctness on two properties:
+--    - they run with async exceptions masked
+--    - they do not race on the same connection
 module Hasura.GraphQL.Transport.WebSocket
-  ( -- | the main handlers for the websocket server
-    onConn,
+  ( onConn,
     onMessage,
     onClose,
-    -- | helpers for sending messages to the client
     sendMsg,
     sendCloseWithMsg,
   )
 where
 
--- NOTE!:
---   The handler functions 'onClose', 'onMessage', etc. depend for correctness on two properties:
---     - they run with async exceptions masked
---     - they do not race on the same connection
-
 import Control.Concurrent.Extended (sleep)
 import Control.Concurrent.STM qualified as STM
 import Control.Monad.Trans.Control qualified as MC