#359 move action's key and description to summary

src/plugins/azgenerator/TemplateAzureCliHelp.ts

@@ -4,8 +4,10 @@
  *--------------------------------------------------------------------------------------------*/
 
 import { CodeModelAz } from "./CodeModelAz"
+import { SchemaType, Parameter, Schema } from "@azure-tools/codemodel";
 import { HeaderGenerator } from "./Header";
-import { ToMultiLine, ToJsonString } from "../../utils/helper"
+import { EscapeString,  ToCamelCase, Capitalize,  ToMultiLine, ToJsonString } from "../../utils/helper"
+import { isNullOrUndefined, isArray } from "util";
 
 const maxShortSummary = 119
 let showExampleStr = "";
@@ -104,7 +106,6 @@ function generateCommandGroupHelp(model: CodeModelAz, subCommandGroupName = "")
         output.push("helps['" + model.CommandGroup_Name + "'] = \"\"\"");
     }
     output.push("    type: group");
-    //output.push("    short-summary: " + model.CommandGroup_Help);
     let shortSummary = "    short-summary: " + model.CommandGroup_Help;
     if(subCommandGroupName != "") {
         shortSummary = shortSummary + " sub group " + subCommandGroupName.split(" ").pop();
@@ -114,6 +115,126 @@ function generateCommandGroupHelp(model: CodeModelAz, subCommandGroupName = "")
     return output;
 }
 
+function addParameterHelp(output: string[], model: CodeModelAz) {
+    let parameter_output = ["    parameters:"];
+
+    let originalOperation = model.Method_GetOriginalOperation;
+    let baseParam = null;
+    if (model.SelectFirstMethodParameter()) {
+        do {
+            if (model.MethodParameter_IsFlattened) {
+                continue;
+            }
+            if (model.MethodParameter_Type == SchemaType.Constant || model.MethodParameter['readOnly']) {
+                continue;
+            }
+            let parameterName = model.MethodParameter_MapsTo;
+            if (!isNullOrUndefined(originalOperation) && model.MethodParameter['targetProperty']?.['isDiscriminator']) {
+                continue;
+            }
+
+            let parameterAlias: string[] = [];
+            if (parameterName.endsWith('name') && parameterName.replace(/_name$|_/g, '') == model.CommandGroup_DefaultName.toLowerCase()) {
+                parameterAlias.push('name');
+                parameterAlias.push('n');
+            }
+            if (!isNullOrUndefined(model.MethodParameter?.language?.['cli']?.['alias'])) {
+                if (!isNullOrUndefined(model.MethodParameter?.language?.['cli']?.['alias'])) {
+                    let alias = model.MethodParameter?.language?.['cli']?.['alias'];
+
+                    if (typeof alias === "string") {
+                        parameterAlias.push(alias);
+                    }
+                    if (isArray(alias)) {
+                        parameterAlias = parameterAlias.concat(alias);
+                    }
+                }
+            }
+            if (parameterAlias.length == 0) parameterAlias.push(parameterName);
+            parameterAlias = parameterAlias.map((alias) => {
+                return '--' + alias.replace(/'/g, '').replace(/_/g, '-');
+            });
+
+            if (model.MethodParameter_IsList && model.MethodParameter_IsListOfSimple && !model.MethodParameter_IsSimpleArray) {
+                if (model.Parameter_IsPolyOfSimple(model.MethodParameter)) {
+                    baseParam = model.MethodParameter;
+                    continue;
+                }
+                let action_output: string[] = [];
+                ToMultiLine(`      - name: ${parameterAlias.join(' ')}`, action_output, 119, true);
+                if (model.MethodParameter_Description && model.MethodParameter_Description.trim().length > 0) {
+                    ToMultiLine(`        short-summary: ${model.MethodParameter_Description.trim()}`.replace(/\r?\n|\r/g, ''), action_output, 119, true);
+                }
+                let options: Parameter[] = [];
+                if (!isNullOrUndefined(model.Schema_ActionName(model.MethodParameter.schema))) {
+                    if (baseParam && model.MethodParameter['polyBaseParam'] == baseParam) {
+                        let keyToMatch = baseParam.schema?.['discriminator']?.property?.language['python']?.name;
+                        let valueToMatch = model.MethodParameter.schema?.['discriminatorValue'];
+                        options = GetActionOptions(model, model.MethodParameter, keyToMatch, valueToMatch);
+                    }
+                    else {
+                        options = GetActionOptions( model, model.MethodParameter);
+                    }
+                }
+                if (options.length > 0) {
+                    action_output.push(`        long-summary: |`);
+                    ToMultiLine(["            Usage:", parameterAlias[0]].concat(options.map(p => `${model.Parameter_NameAz(p)}=XX`)).join(" "), action_output, 119, true);
+                    action_output.push("");
+                    for (let p of options) {
+                        let pDesc = model.Parameter_Description(p);
+                        if (!pDesc || pDesc.trim().length <= 0) continue;
+                        let line = `            ${model.Parameter_NameAz(p)}: `;
+                        if (p.required) line += "Required. ";
+                        line += model.Parameter_Description(p).trim().replace(/\r?\n|\r/g, '');
+                        ToMultiLine(line, action_output, 119, true);
+                    }
+                    if (model.Schema_Type(model.MethodParameter.schema) == SchemaType.Array) {
+                        action_output.push("");
+                        ToMultiLine(`            Multiple actions can be specified by using more than one ${parameterAlias[0]} argument.`, action_output, 119, true);
+                    }
+                    parameter_output = parameter_output.concat(action_output);
+                }
+            }
+        } while (model.SelectNextMethodParameter());
+    }
+
+    if (parameter_output.length>1) {
+        return output.concat(parameter_output);
+    }
+    else {
+        return output;
+    }
+}
+
+
+function GetActionOptions( model: CodeModelAz, param: Parameter, keyToMatch: string = null, valueToMatch: string = null): Parameter[] {
+    let options: Parameter[] = [];
+
+    if (!SchemaType.Object || !SchemaType.Array) {
+        return options;
+    }
+    if (model.EnterSubMethodParameters()) {
+        if (model.SelectFirstMethodParameter()) {
+            do {
+                if (model.SubMethodParameter['readOnly']) {
+                    continue;
+                }
+                if (model.SubMethodParameter['schema']?.type == SchemaType.Constant) {
+                    continue;
+                }
+                if (!isNullOrUndefined(keyToMatch) && !isNullOrUndefined(valueToMatch) && model.Parameter_NamePython(model.SubMethodParameter) == keyToMatch) {
+                    continue;
+                }
+                if (model.SubMethodParameter) {
+                    options.push(model.SubMethodParameter);
+                }
+            } while (model.SelectNextMethodParameter());
+        }
+    }
+    model.ExitSubMethodParameters();
+    return options;
+}
+
 function generateCommandHelp(model: CodeModelAz, needUpdate: boolean = false) {
     // create, delete, list, show, update
     //let method: string = methods[mi];
@@ -130,9 +251,9 @@ function generateCommandHelp(model: CodeModelAz, needUpdate: boolean = false) {
     // there will be just one method for create, update, delete, show, etc.
     // there may be a few list methods, so let's just take description from the first one.
     // as we can't use all of them
-    // output.push("    short-summary: " + model.Command_Help);
     let shortSummary = "    short-summary: " + model.Command_Help;
     ToMultiLine(shortSummary, output, 119, true);
+    output = addParameterHelp(output, model);
 
     let examplesStarted: boolean = false;
 

src/plugins/azgenerator/TemplateAzureCliParams.ts

@@ -285,19 +285,7 @@ function getCommandBody(model: CodeModelAz, needUpdate: boolean = false, needGen
                                     }
                                 }
                                 if (options.length>0) {
-                                    if (options.length>1) {
-                                        argument += " Expect value: KEY1=VALUE1 KEY2=VALUE2 ... , available KEYs are:";
-                                        for (let i =0; i<options.length; i++) {
-                                            argument += " " + options[i];
-                                            if (i<options.length-1) {
-                                                argument += ",";
-                                            }
-                                        }
-                                        argument += ".";
-                                    }
-                                    else {
-                                        argument += ` Expect value: ${options[0]}=xx.`;
-                                    }
+                                    // for those object has known KEYs, the help is in the _help.py file
                                 }
                                 else {
                                     argument += " Expect value: KEY1=VALUE1 KEY2=VALUE2 ...";

src/test/scenarios/attestation/output/src/attestation/azext_attestation/generated/_help.py

@@ -20,6 +20,47 @@
 helps['attestation create-provider'] = """
     type: command
     short-summary: Creates or updates the Attestation Provider.
+    parameters:
+      - name: --policy-signing-certificates-keys
+        short-summary: The value of the "keys" parameter is an array of JWK values.  Bydefault, the order of the JWK va\
+lues within the array does not implyan order of preference among them, although applications of JWK Setscan choose to a\
+ssign a meaning to the order for their purposes, ifdesired.
+        long-summary: |
+            Usage: --policy-signing-certificates-keys alg=XX crv=XX d=XX dp=XX dq=XX e=XX k=XX kid=XX kty=XX n=XX p=XX \
+q=XX qi=XX use=XX x=XX x5-c=XX y=XX
+
+            alg: Required. The "alg" (algorithm) parameter identifies the algorithm intended foruse with the key.  The \
+values used should either be registered in theIANA "JSON Web Signature and Encryption Algorithms" registryestablished b\
+y [JWA] or be a value that contains a Collision-Resistant Name.
+            crv: The "crv" (curve) parameter identifies the curve type
+            d: RSA private exponent or ECC private key
+            dp: RSA Private Key Parameter
+            dq: RSA Private Key Parameter
+            e: RSA public exponent, in Base64
+            k: Symmetric key
+            kid: Required. The "kid" (key ID) parameter is used to match a specific key.  Thisis used, for instance, to\
+ choose among a set of keys within a JWK Setduring key rollover.  The structure of the "kid" value isunspecified.  When\
+ "kid" values are used within a JWK Set, differentkeys within the JWK Set SHOULD use distinct "kid" values.  (Oneexampl\
+e in which different keys might use the same "kid" value is ifthey have different "kty" (key type) values but are consi\
+dered to beequivalent alternatives by the application using them.)  The "kid"value is a case-sensitive string.
+            kty: Required. The "kty" (key type) parameter identifies the cryptographic algorithmfamily used with the ke\
+y, such as "RSA" or "EC". "kty" values shouldeither be registered in the IANA "JSON Web Key Types" registryestablished \
+by [JWA] or be a value that contains a Collision-Resistant Name.  The "kty" value is a case-sensitive string.
+            n: RSA modulus, in Base64
+            p: RSA secret prime
+            q: RSA secret prime, with p < q
+            qi: RSA Private Key Parameter
+            use: Required. Use ("public key use") identifies the intended use ofthe public key. The "use" parameter is \
+employed to indicate whethera public key is used for encrypting data or verifying the signatureon data. Values are comm\
+only "sig" (signature) or "enc" (encryption).
+            x: X coordinate for the Elliptic Curve point
+            x5-c: The "x5c" (X.509 certificate chain) parameter contains a chain of oneor more PKIX certificates [RFC52\
+80].  The certificate chain isrepresented as a JSON array of certificate value strings.  Eachstring in the array is a b\
+ase64-encoded (Section 4 of [RFC4648] --not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value.The PKIX cert\
+ificate containing the key value MUST be the firstcertificate.
+            y: Y coordinate for the Elliptic Curve point
+
+            Multiple actions can be specified by using more than one --policy-signing-certificates-keys argument.
     examples:
       - name: AttestationProviders_Create
         text: |-

src/test/scenarios/attestation/output/src/attestation/azext_attestation/generated/_params.py

@@ -32,9 +32,7 @@ def load_arguments(self, _):
         c.argument('policy_signing_certificates_keys', action=AddPolicySigningCertificatesKeys, nargs='+', help='The va'
                    'lue of the "keys" parameter is an array of JWK values.  By default, the order of the JWK values wit'
                    'hin the array does not imply an order of preference among them, although applications of JWK Sets c'
-                   'an choose to assign a meaning to the order for their purposes, if desired. Expect value: KEY1=VALUE'
-                   '1 KEY2=VALUE2 ... , available KEYs are: alg, crv, d, dp, dq, e, k, kid, kty, n, p, q, qi, use, x, x'
-                   '5-c, y.')
+                   'an choose to assign a meaning to the order for their purposes, if desired.')
 
     with self.argument_context('attestation list-operation') as c:
         pass

src/test/scenarios/datafactory/output/src/datafactory/azext_datafactory/generated/_help.py

@@ -38,6 +38,41 @@
 helps['datafactory create'] = """
     type: command
     short-summary: Creates or updates a factory.
+    parameters:
+      - name: --factory-vsts-configuration
+        short-summary: Factory's VSTS repo information.
+        long-summary: |
+            Usage: --factory-vsts-configuration project-name=XX tenant-id=XX type=XX account-name=XX repository-name=XX\
+ collaboration-branch=XX root-folder=XX last-commit-id=XX
+
+            project-name: Required. VSTS project name.
+            tenant-id: VSTS tenant id.
+            type: Required. Type of repo configuration.
+            account-name: Required. Account name.
+            repository-name: Required. Repository name.
+            collaboration-branch: Required. Collaboration branch.
+            root-folder: Required. Root folder.
+            last-commit-id: Last commit id.
+      - name: --factory-git-hub-configuration
+        short-summary: Factory's GitHub repo information.
+        long-summary: |
+            Usage: --factory-git-hub-configuration host-name=XX type=XX account-name=XX repository-name=XX collaboratio\
+n-branch=XX root-folder=XX last-commit-id=XX
+
+            host-name: GitHub Enterprise host name. For example: https://github.mydomain.com
+            type: Required. Type of repo configuration.
+            account-name: Required. Account name.
+            repository-name: Required. Repository name.
+            collaboration-branch: Required. Collaboration branch.
+            root-folder: Required. Root folder.
+            last-commit-id: Last commit id.
+      - name: --fake-identity
+        short-summary: This is only for az test.
+        long-summary: |
+            Usage: --fake-identity name=XX zones-inside=XX
+
+            name: Required. ..
+            zones-inside: sample of simple array
     examples:
       - name: Factories_CreateOrUpdate
         text: |-
@@ -67,6 +102,34 @@
 helps['datafactory configure-factory-repo'] = """
     type: command
     short-summary: Updates a factory's repo information.
+    parameters:
+      - name: --factory-vsts-configuration
+        short-summary: Factory's VSTS repo information.
+        long-summary: |
+            Usage: --factory-vsts-configuration project-name=XX tenant-id=XX type=XX account-name=XX repository-name=XX\
+ collaboration-branch=XX root-folder=XX last-commit-id=XX
+
+            project-name: Required. VSTS project name.
+            tenant-id: VSTS tenant id.
+            type: Required. Type of repo configuration.
+            account-name: Required. Account name.
+            repository-name: Required. Repository name.
+            collaboration-branch: Required. Collaboration branch.
+            root-folder: Required. Root folder.
+            last-commit-id: Last commit id.
+      - name: --factory-git-hub-configuration
+        short-summary: Factory's GitHub repo information.
+        long-summary: |
+            Usage: --factory-git-hub-configuration host-name=XX type=XX account-name=XX repository-name=XX collaboratio\
+n-branch=XX root-folder=XX last-commit-id=XX
+
+            host-name: GitHub Enterprise host name. For example: https://github.mydomain.com
+            type: Required. Type of repo configuration.
+            account-name: Required. Account name.
+            repository-name: Required. Repository name.
+            collaboration-branch: Required. Collaboration branch.
+            root-folder: Required. Root folder.
+            last-commit-id: Last commit id.
     examples:
       - name: Factories_ConfigureFactoryRepo
         text: |-

src/test/scenarios/datafactory/output/src/datafactory/azext_datafactory/generated/_params.py

@@ -47,15 +47,10 @@ def load_arguments(self, _):
         c.argument('identity', action=AddIdentity, nargs='+', help='Managed service identity of the factory. Expect val'
                    'ue: KEY1=VALUE1 KEY2=VALUE2 ...')
         c.argument('factory_vsts_configuration', action=AddFactoryVstsConfiguration, nargs='+', help='Factory\'s VSTS r'
-                   'epo information. Expect value: KEY1=VALUE1 KEY2=VALUE2 ... , available KEYs are: project-name, tena'
-                   'nt-id, account-name, repository-name, collaboration-branch, root-folder, last-commit-id.',
-                   arg_group='RepoConfiguration')
+                   'epo information.', arg_group='RepoConfiguration')
         c.argument('factory_git_hub_configuration', action=AddFactoryGitHubConfiguration, nargs='+', help='Factory\'s G'
-                   'itHub repo information. Expect value: KEY1=VALUE1 KEY2=VALUE2 ... , available KEYs are: host-name, '
-                   'account-name, repository-name, collaboration-branch, root-folder, last-commit-id.', arg_group='Repo'
-                   'Configuration')
-        c.argument('fake_identity', action=AddFakeIdentity, nargs='+', help='This is only for az test. Expect value: KE'
-                   'Y1=VALUE1 KEY2=VALUE2 ... , available KEYs are: name, zones-inside.')
+                   'itHub repo information.', arg_group='RepoConfiguration')
+        c.argument('fake_identity', action=AddFakeIdentity, nargs='+', help='This is only for az test.')
         c.argument('zones', nargs='+', help='This is only for az test.')
 
     with self.argument_context('datafactory update') as c:
@@ -73,13 +68,9 @@ def load_arguments(self, _):
         c.argument('location_id', help='The location identifier.', id_part='name')
         c.argument('factory_resource_id', help='The factory resource id.')
         c.argument('factory_vsts_configuration', action=AddFactoryVstsConfiguration, nargs='+', help='Factory\'s VSTS r'
-                   'epo information. Expect value: KEY1=VALUE1 KEY2=VALUE2 ... , available KEYs are: project-name, tena'
-                   'nt-id, account-name, repository-name, collaboration-branch, root-folder, last-commit-id.',
-                   arg_group='RepoConfiguration')
+                   'epo information.', arg_group='RepoConfiguration')
         c.argument('factory_git_hub_configuration', action=AddFactoryGitHubConfiguration, nargs='+', help='Factory\'s G'
-                   'itHub repo information. Expect value: KEY1=VALUE1 KEY2=VALUE2 ... , available KEYs are: host-name, '
-                   'account-name, repository-name, collaboration-branch, root-folder, last-commit-id.', arg_group='Repo'
-                   'Configuration')
+                   'itHub repo information.', arg_group='RepoConfiguration')
 
     with self.argument_context('datafactory get-data-plane-access') as c:
         c.argument('resource_group_name', resource_group_name_type)