feat(sdk): resource docs

codegen/pkg/generator/generator.go

@@ -321,6 +321,13 @@ func (g *Generator) displayTagName(tagKey string) string {
 	return sanitizeTagName(tagKey)
 }
 
+func (g *Generator) tagDescription(tagKey string) string {
+	if tag, ok := g.tagLookup[tagKey]; ok && tag != nil {
+		return strings.TrimSpace(tag.Description)
+	}
+	return ""
+}
+
 func (g *Generator) namespaceForTag(tagKey string) string {
 	if tagKey == sharedTagKey {
 		return sharedTagNamespace

codegen/pkg/generator/services.go

@@ -88,7 +88,21 @@ func (g *Generator) buildServiceBlock(tagKey string, operations []*operation) st
 		buf.WriteString("\n")
 	}
 
-	fmt.Fprintf(&buf, "/**\n * Class %s\n *\n * @package SumUp\\Services\n */\n", className)
+	fmt.Fprintf(&buf, "/**\n * Class %s\n", className)
+	if description := g.tagDescription(tagKey); description != "" {
+		buf.WriteString(" *\n")
+		for _, line := range strings.Split(description, "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" {
+				buf.WriteString(" *\n")
+				continue
+			}
+			buf.WriteString(" * ")
+			buf.WriteString(line)
+			buf.WriteString("\n")
+		}
+	}
+	buf.WriteString(" *\n * @package SumUp\\Services\n */\n")
 	fmt.Fprintf(&buf, "class %s implements SumUpService\n{\n", className)
 	buf.WriteString("    /**\n")
 	buf.WriteString("     * The client for the http communication.\n")

codegen/pkg/generator/sumup.go

@@ -153,6 +153,13 @@ class SumUp
 
 	for _, service := range services {
 		method := strcase.ToLowerCamel(service)
+		buf.WriteString("    /**\n")
+		fmt.Fprintf(&buf, "     * Access the %s API endpoints.\n", service)
+		buf.WriteString("     *\n")
+		fmt.Fprintf(&buf, "     * @return %s\n", service)
+		buf.WriteString("     *\n")
+		buf.WriteString("     * @throws ConfigurationException\n")
+		buf.WriteString("     */\n")
 		fmt.Fprintf(&buf, "    public function %s()\n", method)
 		buf.WriteString("    {\n")
 		buf.WriteString("        if (empty($this->accessToken)) {\n")

src/Checkouts/Checkouts.php

@@ -75,6 +75,12 @@ class CheckoutsListAvailablePaymentMethodsParams
 /**
  * Class Checkouts
  *
+ * Accept payments from your end users by adding the Checkouts model to your platform.
+ * SumUp supports standard and single payment 3DS checkout flows.
+ *
+ * The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts.
+ * A payment is completed by creating a checkout and then processing the checkout.
+ *
  * @package SumUp\Services
  */
 class Checkouts implements SumUpService

src/Customers/Customers.php

@@ -38,6 +38,11 @@ public function __construct(array $data = [])
 /**
  * Class Customers
  *
+ * Allow your regular customers to save their information with the Customers model.
+ * This will prevent re-entering payment instrument information for recurring payments on your platform.
+ *
+ * Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers.
+ *
  * @package SumUp\Services
  */
 class Customers implements SumUpService

src/Members/Members.php

@@ -218,6 +218,8 @@ class MembersListParams
 /**
  * Class Members
  *
+ * Endpoints to manage account members. Members are users that have membership within merchant accounts.
+ *
  * @package SumUp\Services
  */
 class Members implements SumUpService

src/Memberships/Memberships.php

@@ -111,6 +111,8 @@ class MembershipsListParams
 /**
  * Class Memberships
  *
+ * Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.
+ *
  * @package SumUp\Services
  */
 class Memberships implements SumUpService

src/Merchants/Merchants.php

@@ -62,6 +62,8 @@ class MerchantsListPersonsParams
 /**
  * Class Merchants
  *
+ * Merchant account represents a single business entity at SumUp.
+ *
  * @package SumUp\Services
  */
 class Merchants implements SumUpService

src/Payouts/Payouts.php

@@ -96,6 +96,9 @@ class PayoutsListDeprecatedParams
 /**
  * Class Payouts
  *
+ * The Payouts model will allow you to track funds you’ve received from SumUp.
+ * You can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint.
+ *
  * @package SumUp\Services
  */
 class Payouts implements SumUpService

src/Readers/Readers.php

@@ -101,6 +101,8 @@ class ReadersListResponse
 /**
  * Class Readers
  *
+ * A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.
+ *
  * @package SumUp\Services
  */
 class Readers implements SumUpService

src/Receipts/Receipts.php

@@ -37,6 +37,8 @@ class ReceiptsGetParams
 /**
  * Class Receipts
  *
+ * The Receipts model obtains receipt-like details for specific transactions.
+ *
  * @package SumUp\Services
  */
 class Receipts implements SumUpService

src/Roles/Roles.php

@@ -106,6 +106,8 @@ class RolesListResponse
 /**
  * Class Roles
  *
+ * Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.
+ *
  * @package SumUp\Services
  */
 class Roles implements SumUpService

src/Subaccounts/Subaccounts.php

@@ -182,6 +182,8 @@ class SubaccountsListSubAccountsParams
 /**
  * Class Subaccounts
  *
+ * Endpoints for managing merchant sub-accounts (operators).
+ *
  * @package SumUp\Services
  */
 class Subaccounts implements SumUpService

src/SumUp.php

@@ -156,56 +156,111 @@ private function normalizeConfig(array $config): array
         return $config;
     }
 
+    /**
+     * Access the Checkouts API endpoints.
+     *
+     * @return Checkouts
+     */
     public function checkouts(): Checkouts
     {
         return new Checkouts($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Customers API endpoints.
+     *
+     * @return Customers
+     */
     public function customers(): Customers
     {
         return new Customers($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Members API endpoints.
+     *
+     * @return Members
+     */
     public function members(): Members
     {
         return new Members($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Memberships API endpoints.
+     *
+     * @return Memberships
+     */
     public function memberships(): Memberships
     {
         return new Memberships($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Merchants API endpoints.
+     *
+     * @return Merchants
+     */
     public function merchants(): Merchants
     {
         return new Merchants($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Payouts API endpoints.
+     *
+     * @return Payouts
+     */
     public function payouts(): Payouts
     {
         return new Payouts($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Readers API endpoints.
+     *
+     * @return Readers
+     */
     public function readers(): Readers
     {
         return new Readers($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Receipts API endpoints.
+     *
+     * @return Receipts
+     */
     public function receipts(): Receipts
     {
         return new Receipts($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Roles API endpoints.
+     *
+     * @return Roles
+     */
     public function roles(): Roles
     {
         return new Roles($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Subaccounts API endpoints.
+     *
+     * @return Subaccounts
+     */
     public function subaccounts(): Subaccounts
     {
         return new Subaccounts($this->client, $this->resolveAccessToken());
     }
 
+    /**
+     * Access the Transactions API endpoints.
+     *
+     * @return Transactions
+     */
     public function transactions(): Transactions
     {
         return new Transactions($this->client, $this->resolveAccessToken());

src/Transactions/Transactions.php

@@ -340,6 +340,9 @@ class TransactionsListDeprecatedParams
 /**
  * Class Transactions
  *
+ * Retrieve details for a specific transaction by it’s `id`
+ * or any other required query parameter, or list all transactions related to the merchant account.
+ *
  * @package SumUp\Services
  */
 class Transactions implements SumUpService