[PowerShell][Experimental] Better docstring (#5688)

* add docstring to powershell module

* add doc string

Author: wing328

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/PowerShellExperimentalClientCodegen.java

@@ -594,7 +594,7 @@ public String toParamName(String name) {
     public Map<String, Object> postProcessOperationsWithModels(Map<String, Object> objs, List<Object> allModels) {
         Map<String, Object> operations = (Map<String, Object>) objs.get("operations");
         HashMap<String, CodegenModel> modelMaps = new HashMap<String, CodegenModel>();
-        HashMap<String, Boolean> processedModelMaps = new HashMap<String, Boolean>();
+        HashMap<String, Integer> processedModelMaps = new HashMap<String, Integer>();
 
         for (Object o : allModels) {
             HashMap<String, Object> h = (HashMap<String, Object>) o;
@@ -672,7 +672,7 @@ public String toVarName(String name) {
         return name;
     }
 
-    private String constructExampleCode(CodegenParameter codegenParameter, HashMap<String, CodegenModel> modelMaps, HashMap<String, Boolean> processedModelMap) {
+    private String constructExampleCode(CodegenParameter codegenParameter, HashMap<String, CodegenModel> modelMaps, HashMap<String, Integer> processedModelMap) {
         if (codegenParameter.isListContainer) { // array
             return "@(" + constructExampleCode(codegenParameter.items, modelMaps, processedModelMap) + ")";
         } else if (codegenParameter.isMapContainer) { // TODO: map, file type
@@ -714,7 +714,7 @@ private String constructExampleCode(CodegenParameter codegenParameter, HashMap<S
         }
     }
 
-    private String constructExampleCode(CodegenProperty codegenProperty, HashMap<String, CodegenModel> modelMaps, HashMap<String, Boolean> processedModelMap) {
+    private String constructExampleCode(CodegenProperty codegenProperty, HashMap<String, CodegenModel> modelMaps, HashMap<String, Integer> processedModelMap) {
         if (codegenProperty.isListContainer) { // array
             return "@(" + constructExampleCode(codegenProperty.items, modelMaps, processedModelMap) + ")";
         } else if (codegenProperty.isMapContainer) { // map
@@ -756,15 +756,23 @@ private String constructExampleCode(CodegenProperty codegenProperty, HashMap<Str
         }
     }
 
-    private String constructExampleCode(CodegenModel codegenModel, HashMap<String, CodegenModel> modelMaps, HashMap<String, Boolean> processedModelMap) {
+    private String constructExampleCode(CodegenModel codegenModel, HashMap<String, CodegenModel> modelMaps, HashMap<String, Integer> processedModelMap) {
         String example;
 
         // break infinite recursion. Return, in case a model is already processed in the current context.
         String model = codegenModel.name;
         if (processedModelMap.containsKey(model)) {
-            return "";
+            int count = processedModelMap.get(model);
+            if (count == 1) {
+                processedModelMap.put(model, 2);
+            } else if (count == 2) {
+                return "";
+            } else {
+                throw new RuntimeException("Invalid count when constructing example: " + count);
+            }
+        } else {
+            processedModelMap.put(model, 1);
         }
-        processedModelMap.put(model, true);
 
         example = "(New-" + codegenModel.name;
         List<String> propertyExamples = new ArrayList<>();

modules/openapi-generator/src/main/resources/powershell-experimental/api.mustache

@@ -1,6 +1,24 @@
 {{> partial_header}}
 {{#operations}}
 {{#operation}}
+<#
+.SYNOPSIS
+
+{{#summary}}{{{.}}}{{/summary}}{{^summary}}No summary available.{{/summary}}
+
+.DESCRIPTION
+
+{{#description}}{{{description}}}{{/description}}{{^description}}No description available.{{/description}}
+
+{{#allParams}}
+.PARAMETER {{{paramName}}}
+{{#description}}{{{description}}}{{/description}}{{^description}}No description available.{{/description}}
+
+{{/allParams}}
+.OUTPUTS
+
+{{#returnType}}{{{.}}}{{/returnType}}{{^returnType}}None{{/returnType}}
+#>
 function {{{vendorExtensions.x-powershell-method-name}}} {
     [CmdletBinding()]
     Param (

modules/openapi-generator/src/main/resources/powershell-experimental/configuration.mustache

@@ -1,4 +1,17 @@
 {{> partial_header}}
+<#
+.SYNOPSIS
+
+Get the configuration object '{{apiNamePrefix}}Configuration'.
+
+.DESCRIPTION
+
+Get the configuration object '{{apiNamePrefix}}Configuration'.
+
+.OUTPUTS
+
+System.Collections.Hashtable
+#>
 function Get-{{apiNamePrefix}}Configuration {
 
     $Configuration = $Script:Configuration
@@ -36,6 +49,43 @@ function Get-{{apiNamePrefix}}Configuration {
 
 }
 
+<#
+.SYNOPSIS
+
+Set the configuration.
+
+.DESCRIPTION
+
+Set the configuration.
+
+.PARAMETER BaseUrl
+Base URL of the HTTP endpoints
+
+.PARAMETER Username
+Username in HTTP basic authentication
+
+.PARAMETER Passowrd
+Password in HTTP basic authentication
+
+.PARAMETER ApiKey
+API Keys for authentication/authorization
+
+.PARAMETER ApiKeyPrefix
+Prefix in the API Keys
+
+.PARAMETER Cookie
+Cookie for authentication/authorization
+
+.PARAMETER AccessToken
+Access token for authentication/authorization
+
+.PARAMETER SkipCertificateCheck
+Skip certificate verification
+
+.OUTPUTS
+
+System.Collections.Hashtable
+#>
 function Set-{{{apiNamePrefix}}}Configuration {
 
     [CmdletBinding()]
@@ -92,6 +142,25 @@ function Set-{{{apiNamePrefix}}}Configuration {
     }
 }
 
+<#
+.SYNOPSIS
+
+Set the API Key.
+
+.DESCRIPTION
+
+Set the API Key.
+
+.PARAMETER Id
+ID of the security schema
+
+.PARAMETER ApiKey
+API Key
+
+.OUTPUTS
+
+None
+#>
 function Set-{{{apiNamePrefix}}}ConfigurationApiKey {
     [CmdletBinding()]
     Param(
@@ -107,6 +176,25 @@ function Set-{{{apiNamePrefix}}}ConfigurationApiKey {
     }
 }
 
+<#
+.SYNOPSIS
+
+Set the API Key prefix.
+
+.DESCRIPTION
+
+Set the API Key prefix.
+
+.PARAMETER Id
+ID of the security schema
+
+.PARAMETER ApiKey
+API Key prefix
+
+.OUTPUTS
+
+None
+#>
 function Set-{{{apiNamePrefix}}}ConfigurationApiKeyPrefix {
     [CmdletBinding()]
     Param(

modules/openapi-generator/src/main/resources/powershell-experimental/model.mustache

@@ -1,6 +1,25 @@
 {{> partial_header}}
 {{#models}}
 {{#model}}
+<#
+.SYNOPSIS
+
+{{#summary}}{{{.}}}{{/summary}}{{^summary}}No summary available.{{/summary}}
+
+.DESCRIPTION
+
+{{#description}}{{{description}}}{{/description}}{{^description}}No description available.{{/description}}
+
+{{#vars}}
+.PARAMETER {{{name}}}
+{{#description}}{{{description}}}{{/description}}{{^description}}No description available.{{/description}}
+
+{{/vars}}
+.OUTPUTS
+
+{{{classname}}}<PSCustomObject>
+#>
+
 function New-{{{apiNamePrefix}}}{{{classname}}} {
     [CmdletBinding()]
     Param (

samples/client/petstore/powershell-experimental/docs/PSUserApi.md

@@ -131,7 +131,7 @@ $Configuration["ApiKey"]["AUTH_KEY"] = "YOUR_API_KEY"
 # Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
 #$Configuration["ApiKeyPrefix"]["AUTH_KEY"] = "Bearer"
 
-$User = @((New-User -Id 123  -Username "Username_example"  -FirstName "FirstName_example"  -LastName "LastName_example"  -Email "Email_example"  -Password "Password_example"  -Phone "Phone_example"  -UserStatus 123)) # User[] | List of user object
+$User = @() # User[] | List of user object
 
 # Creates list of users with given input array
 try {
@@ -368,7 +368,7 @@ $Configuration["ApiKey"]["AUTH_KEY"] = "YOUR_API_KEY"
 #$Configuration["ApiKeyPrefix"]["AUTH_KEY"] = "Bearer"
 
 $Username = "Username_example" # String | name that need to be deleted (default to null)
-$User = (New-User -Id 123  -Username "Username_example"  -FirstName "FirstName_example"  -LastName "LastName_example"  -Email "Email_example"  -Password "Password_example"  -Phone "Phone_example"  -UserStatus 123) # User | Updated user object
+$User =  # User | Updated user object
 
 # Updated user
 try {