fix: change overload order to not show the deprecation per default [HOMER-1999] (#1841)

* fix: change overload order to not show the deprecation per default

* chore: give a clear recommendation how to fix the deprecation

* chore: add comment mentioning why we do this

* Update lib/contentful-management.ts

Co-authored-by: Kristoffer <[email protected]>

---------

Co-authored-by: Kristoffer <[email protected]>

Author: Chaoste

lib/contentful-management.ts

@@ -43,17 +43,6 @@ interface UserAgentParams {
 export type ClientParams = RestAdapterParams & UserAgentParams
 type ClientOptions = UserAgentParams & XOR<RestAdapterParams, AdapterParams>
 
-/**
- * @deprecated the alphaFeatures option is not longer supported
- */
-function createClient(
-  params: ClientOptions,
-  opts: {
-    type?: 'plain'
-    alphaFeatures: string[]
-    defaults?: DefaultParams
-  }
-): ClientAPI | PlainClientAPI
 /**
  * Create a client instance
  * @param params - Client initialization parameters
@@ -72,6 +61,18 @@ function createClient(
     defaults?: DefaultParams
   }
 ): PlainClientAPI
+// Usually, overloads with more specific signatures should come first but some IDEs are often not able to handle overloads with separate TSDocs correctly
+/**
+ * @deprecated The `alphaFeatures` option is no longer supported. Please use the function without this option.
+ */
+function createClient(
+  params: ClientOptions,
+  opts: {
+    type?: 'plain'
+    alphaFeatures: string[]
+    defaults?: DefaultParams
+  }
+): ClientAPI | PlainClientAPI
 function createClient(
   params: ClientOptions,
   opts: {