Turn long summaries into descriptions (#3706)

* Turn long summaries into descriptions

Author: pcapriotti

changelog.d/4-docs/long-summaries

@@ -0,0 +1 @@
+Turn long summaries in openapi documentation into descriptions

libs/wire-api/src/Wire/API/Routes/Public/Brig.hs

@@ -684,9 +684,8 @@ type PrekeyAPI =
     :<|> Named
            "get-multi-user-prekey-bundle-unqualified"
            ( Summary
-               "(deprecated)  Given a map of user IDs to client IDs return a \
-               \prekey for each one. You can't request information for more users than \
-               \maximum conversation size."
+               "(deprecated)  Given a map of user IDs to client IDs return a prekey for each one."
+               :> Description "You can't request information for more users than maximum conversation size."
                :> Until 'V2
                :> ZUser
                :> "users"
@@ -697,9 +696,8 @@ type PrekeyAPI =
     :<|> Named
            "get-multi-user-prekey-bundle-qualified@v3"
            ( Summary
-               "Given a map of domain to (map of user IDs to client IDs) return a \
-               \prekey for each one. You can't request information for more users than \
-               \maximum conversation size."
+               "(deprecated)  Given a map of user IDs to client IDs return a prekey for each one."
+               :> Description "You can't request information for more users than maximum conversation size."
                :> MakesFederatedCall 'Brig "claim-multi-prekey-bundle"
                :> ZUser
                :> Until 'V4
@@ -711,9 +709,8 @@ type PrekeyAPI =
     :<|> Named
            "get-multi-user-prekey-bundle-qualified"
            ( Summary
-               "Given a map of domain to (map of user IDs to client IDs) return a \
-               \prekey for each one. You can't request information for more users than \
-               \maximum conversation size."
+               "(deprecated)  Given a map of user IDs to client IDs return a prekey for each one."
+               :> Description "You can't request information for more users than maximum conversation size."
                :> MakesFederatedCall 'Brig "claim-multi-prekey-bundle"
                :> ZUser
                :> From 'V4
@@ -1570,10 +1567,10 @@ type TeamsAPI =
            )
     :<|> Named
            "get-team-size"
-           ( Summary
-               "Returns the number of team members as an integer.  \
-               \Can be out of sync by roughly the `refresh_interval` \
-               \of the ES index."
+           ( Summary "Get the number of team members as an integer"
+               :> Description
+                    "Can be out of sync by roughly the `refresh_interval` \
+                    \of the ES index."
                :> CanThrow 'InvalidInvitationCode
                :> ZUser
                :> "teams"

libs/wire-api/src/Wire/API/Routes/Public/Galley/Conversation.hs

@@ -723,10 +723,10 @@ type ConversationAPI =
     -- - MemberJoin event to members
     :<|> Named
            "join-conversation-by-code-unqualified"
-           ( Summary
-               "Join a conversation using a reusable code.\
-               \If the guest links team feature is disabled, this will fail with 409 GuestLinksDisabled.\
-               \Note that this is currently inconsistent (for backwards compatibility reasons) with `POST /conversations/code-check` which responds with 404 CodeNotFound if guest links are disabled."
+           ( Summary "Join a conversation using a reusable code"
+               :> Description
+                    "If the guest links team feature is disabled, this will fail with 409 GuestLinksDisabled.\
+                    \Note that this is currently inconsistent (for backwards compatibility reasons) with `POST /conversations/code-check` which responds with 404 CodeNotFound if guest links are disabled."
                :> MakesFederatedCall 'Galley "on-conversation-updated"
                :> CanThrow 'CodeNotFound
                :> CanThrow 'InvalidConversationPassword
@@ -745,10 +745,10 @@ type ConversationAPI =
            )
     :<|> Named
            "code-check"
-           ( Summary
-               "Check validity of a conversation code.\
-               \If the guest links team feature is disabled, this will fail with 404 CodeNotFound.\
-               \Note that this is currently inconsistent (for backwards compatibility reasons) with `POST /conversations/join` which responds with 409 GuestLinksDisabled if guest links are disabled."
+           ( Summary "Check validity of a conversation code."
+               :> Description
+                    "If the guest links team feature is disabled, this will fail with 404 CodeNotFound.\
+                    \Note that this is currently inconsistent (for backwards compatibility reasons) with `POST /conversations/join` which responds with 409 GuestLinksDisabled if guest links are disabled."
                :> CanThrow 'CodeNotFound
                :> CanThrow 'ConvNotFound
                :> CanThrow 'InvalidConversationPassword