Improve docstrings, try to localize suppressions

specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/common.tsp

@@ -36,12 +36,10 @@ model NetworkIdentifier {
   @doc("The type of identifier for the network. one of: 'IPv4', 'IPv6', 'NetworkCode'")
   identifierType: string;
 
-  /**
-  The network identifier in a format matching the type above:
-  - IPv4 of a device in dotted-quad form 1.2.3.4.
-  - IPv6 of a device in IETF 5952 format.
-  - NetworkCode matching our documentation or an output from /Network:retrieve."
-  */
+  @doc("""
+    The network identifier, based on the identifierType: an IPv4 address, and IPv6 address, or a Network Code.
+    A Network Code may be obtained from APC documentation or from the APC /Network:retrieve endpoint.
+    """)
   identifier: string;
 }
 
@@ -91,10 +89,7 @@ model Ipv6AddressModel {
 
 @doc("IPv4 device indicator")
 model Ipv4Address {
-  /** IPv4 address may be specified in form <address/mask> as:
-          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
-          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
-            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. */
+  @doc("An IPv4 address. This may be specified as an exact address, or as a subnet in CIDR notation.")
   ipv4: string;
 
   @doc("User equipment port.")
@@ -103,13 +98,7 @@ model Ipv4Address {
 
 @doc("IPv6 device indicator")
 model Ipv6Address {
-  /** IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:
-          - address - The /128 subnet is optional for single addresses:
-            - 2001:db8:85a3:8d3:1319:8a2e:370:7344
-            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
-          - address/mask - an IP v6 number with a mask:
-            - 2001:db8:85a3:8d3::0/64
-            - 2001:db8:85a3:8d3::/64 */
+  @doc("An IPv6 address. This may be specified as an exact address, or as a subnet in CIDR notation.")
   ipv6: string;
 
   @doc("User equipment port.")

specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/location.tsp

@@ -51,7 +51,7 @@ model DeviceLocationVerificationContent {
   @maxValue(100)
   accuracy: int32;
 
-  @doc("The device to find the location for.")
+  @doc("The device to find the location for. Exactly one of Network Access Identifier, Phone Number, IPv4, or IPv6 must be provided")
   locationDevice: LocationDevice;
 }
 

specification/programmableconnectivity/Azure.ProgrammableConnectivity/apis/number.tsp

@@ -13,26 +13,24 @@ namespace Azure.ProgrammableConnectivity;
 @doc("""
   Number operations include Frontend Authentication.
 
-  Users must first make a call to triggerFrontendAuthentication, which redirects the device
-  to the device's Network to authenticate directly. The Network responds with a token.
+  Users first make a call to the endpoint /Number:verify, which returns a redirect to the device's 
+  Network. This is followed by the device to authenticate directly with the Network. The Network 
+  responds with a token and a redirect. This token can be exchanged with APC for a code.
   
-  This redirects the device to APC, where the token is used to verify / retrieve
-  the device number. The second response is a 200 containing the result of the query.
+  Users make a second call to the endpoint /Number:verify including the code. The code is used 
+  to verify the device number. The second response is a 200 containing the result of the query.
 
-  This flow requires some manual interaction from the developer between receiving the 302 redirect,
-  and making a second call to obtain the number verification result. This has therefore been
-  split into two operations, one for the redirect, and one for the result.
+  For more information on the steps required to use Number Verificaiton, see the APC documentation.
 """)
 interface NumberVerification {
+  #suppress "@azure-tools/typespec-azure-core/no-response-body" "302 redirect has no response body"
   @doc("Verifies the phone number (MSISDN) associated with a device. As part of the frontend authorization flow, the device is redirected to the operator network to authenticate directly.")
   @sharedRoute
   @action("verify")
   verifyWithoutCode is Operations.ResourceAction<
     NumberVerificationEndpoint,
     NumberVerificationWithoutCodeContent,
-    // Typespec requires that non-204 responses have a non-empty body. This requirement cannot be suppressed.
-    // Return a model containing only one optional field to get around this.
-    TypeSpec.Http.Response<302> & EmptyResult,
+    TypeSpec.Http.Response<302> & {},
     TraitOverride<ResponseHeadersTrait<{
       @header location: string;
     } & RequestIdResponseHeader>>

specification/programmableconnectivity/data-plane/Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json

@@ -201,9 +201,6 @@
         "responses": {
           "302": {
             "description": "Redirection",
-            "schema": {
-              "$ref": "#/definitions/EmptyResult"
-            },
             "headers": {
               "location": {
                 "type": "string"
@@ -612,7 +609,7 @@
         },
         "locationDevice": {
           "$ref": "#/definitions/LocationDevice",
-          "description": "The device to find the location for."
+          "description": "The device to find the location for. Exactly one of Network Access Identifier, Phone Number, IPv4, or IPv6 must be provided"
         }
       },
       "required": [
@@ -672,7 +669,7 @@
       "properties": {
         "ipv4": {
           "type": "string",
-          "description": "IPv4 address may be specified in form <address/mask> as:\n          - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.\n          - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.\n            In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version."
+          "description": "An IPv4 address. This may be specified as an exact address, or as a subnet in CIDR notation."
         },
         "port": {
           "type": "integer",
@@ -701,7 +698,7 @@
       "properties": {
         "ipv6": {
           "type": "string",
-          "description": "IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:\n          - address - The /128 subnet is optional for single addresses:\n            - 2001:db8:85a3:8d3:1319:8a2e:370:7344\n            - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128\n          - address/mask - an IP v6 number with a mask:\n            - 2001:db8:85a3:8d3::0/64\n            - 2001:db8:85a3:8d3::/64"
+          "description": "An IPv6 address. This may be specified as an exact address, or as a subnet in CIDR notation."
         },
         "port": {
           "type": "integer",
@@ -767,7 +764,7 @@
         },
         "identifier": {
           "type": "string",
-          "description": "The network identifier in a format matching the type above:\n  - IPv4 of a device in dotted-quad form 1.2.3.4.\n  - IPv6 of a device in IETF 5952 format.\n  - NetworkCode matching our documentation or an output from /Network:retrieve.\""
+          "description": "The network identifier, based on the identifierType: an IPv4 address, and IPv6 address, or a Network Code.\nA Network Code may be obtained from APC documentation or from the APC /Network:retrieve endpoint."
         }
       },
       "required": [

specification/programmableconnectivity/data-plane/readme.md

@@ -39,7 +39,8 @@ input-file:
   - Azure.ProgrammableConnectivity/preview/2024-02-09-preview/openapi.json
 suppressions:
   - code: ValidResponseCodeRequired
-    reason: APC must return a 302 as part of a non-standard 
+    reason: APC must return a 302 as part of a non-standard frontend authentication flow
+    where: $.paths./number-verification/number:verify.post.responses
 ```
 
 # Code Generation