Feature Request: Expand Comment-Based Help Content of ResourceType and PropertyType Functions

[ScriptAutomate]

I was playing around with a similar idea of auto-generating a PowerShell module like this before in the past, and while revisiting it I saw that you've already done a ton of work. This is a feature request with example code in case it would be helpful since my code is going unused.

My pipeline, for function generation, initially did the following:

• Download latest CFN resource spec file.
• git clone / pull for the latest of the AWS Cloudformation User Guide repo.
  • All documentation in awsdocs/aws-cloudformation-user-guide/doc_source has the same name as the HTML endpoints of the Documentation property URLs in the CloudFormationResourceSpecification.json - the extension only needs to be changed to .md
• Begin creating a function for every resourcetype and every propertytype from the spec file
  • When generating the comment-based help, parse out the following for each function from the aws markdown docs:
  • SYNOPSIS : As you currently are doing
  • DESCRIPTION: SYNOPSIS info, plus all paragraphs of the official aws help doc before Syntax markdown header.
  • PARAMETER descriptions from official aws help doc

The results for PARAMETER descriptions could accompany the current inclusions of PrimitiveType, Documentation, and UpdateType. Required is unnecessary to include since PowerShell is already checking whether [parameter(Mandatory = $true)] is present, which results in Required? output being true or false.

New-VSAlexaAskSkill Example

Differences in help documentation output could look like this, using New-VSAlexaAskSkill as an example.

• Documentation: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ask-skill.html
• AWS Doc repo equivalent file path: aws-cloudformation-user-guide/doc_source/aws-resource-ask-skill.md

Parameter Information (Current)

PS> Get-Help New-VSAlexaAskSkill -Parameter VendorId

-VendorId <Object>
    Required: True    
    Documentation: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ask-skill.html#cfn-ask-skill-vendorid   
    PrimitiveType: String    
    UpdateType: Immutable
    
    Required?                    true
    Position?                    named
    Default value                
    Accept pipeline input?       false
    Accept wildcard characters?  false

Parameter Information (Expanded)

Includes parsed data from Alexa::ASK::Skill

PS> Get-Help New-VSAlexaAskSkill -Parameter VendorId

-VendorId <Object>
    The vendor ID associated with the Amazon developer account that 
    will host the skill. Details for retrieving the vendor ID are in 
    How to get your vendor ID: https://github.com/alexa/alexa-smartho
    me/wiki/How-to-get-your-vendor-ID. The provided LWA credentials 
    must be linked to the developer account associated with this 
    vendor ID.

    Documentation: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ask-skill.html#cfn-ask-skill-vendorid   
    PrimitiveType: String    
    UpdateType: Immutable
    
    Required?                    true
    Position?                    named
    Default value                
    Accept pipeline input?       false
    Accept wildcard characters?  false

NOTE: Required property can be dropped, because PowerShell help output will automatically check whether [parameter(Mandatory = $true)] which results in Required? output being true or false.

Description Information (Current)

PS> Get-Help New-VSAlexaAskSkill

NAME
    New-VSAlexaAskSkill
    
SYNOPSIS
    Adds an Alexa::ASK::Skill resource to the template
...

DESCRIPTION
    Adds an Alexa::ASK::Skill resource to the template
...

Description Information (Expanded)

Includes parsed data from Alexa::ASK::Skill

PS> Get-Help New-VSAlexaAskSkill

NAME
    New-VSAlexaAskSkill
    
SYNOPSIS
    Adds an Alexa::ASK::Skill resource to the template
...

DESCRIPTION
    The Alexa::ASK::Skill resource creates an Alexa skill that 
    enables customers to access new abilities. For more information 
    about developing a skill, see the Build Skills with the Alexa 
    Skills Kit developer documentation: https://developer.amazon.com/
    docs/ask-overviews/build-skills-with-the-alexa-skills-kit.html.

I created some sloppy code here that goes through and generates objects with help documentation contents, which is what my module originally used: PowerShell Helpers Proof-of-Concept for Comment-Based Help Generation via Parsing of AWS CFN UserGuide GitHub Docs

If this seems like a welcome feature to be added to this module, I hope the code / method works.

[scrthq]

This is great!!! Definitely going to expand it a bit, totally makes sense and adds a ton of value!! Thank you for the suggestion and sample code!

[ScriptAutomate]

Awesome. Also, when running my code example, all of the WARNING messages that will pop-up are directly related to problems having to do with both the AWS CFN UserGuide documentation and the CloudFormationSpecification.json files that are outside of our control at the moment. This has to do with broken links in the cfn spec json, and with documentation that hasn't yet been pushed to the source repo (which makes the source repo sound more like a periodic source repo copy).

• I am chronicling the issue here: Several Docs Missing in Repo, but Referenced and Published on Live AWS User Guide?
• And have made a repo here that is attempting to assist: AWS CloudFormation Library - A Completely Tracked and Versioned Collection Store of CloudFormationResource.json Resource Specification Files

[scrthq]

Incredibly valuable, thank you so much for sharing!! Also, contributors are very much welcome if interested! It seems like we've been solving a lot of the same things from different aspects. I appreciate your insight and suggestions @ScriptAutomate!

[ScriptAutomate]

Just tested, and looks exactly as expected with the latest PowerShell Gallery version based on my above examples:

PS> Get-Module VaporShell | select Name,Version     

Name       Version
----       -------
VaporShell 2.9.1

PS> Get-Help New-VSAlexaASKSkill -Parameter VendorId

-VendorId <Object>
    The vendor ID associated with the Amazon developer account that 
    will host the skill. Details for retrieving the vendor ID are in 
    How to get your vendor ID: https://github.com/alexa/alexa-smartho
    me/wiki/How-to-get-your-vendor-ID. The provided LWA credentials 
    must be linked to the developer account associated with this 
    vendor ID.
    
    Documentation: http://docs.aws.amazon.com/AWSCloudFormation/lates
    t/UserGuide/aws-resource-ask-skill.html#cfn-ask-skill-vendorid
    PrimitiveType: String
    UpdateType: Immutable
    
    Required?                    true
    Position?                    named
    Default value                
    Accept pipeline input?       false
    Accept wildcard characters?  false

PS> Get-Help New-VSAlexaASKSkill

NAME
    New-VSAlexaASKSkill
    
SYNOPSIS
    Adds an Alexa::ASK::Skill resource to the template. The 
    Alexa::ASK::Skill resource creates an Alexa skill that enables 
    customers to access new abilities. For more information about 
    developing a skill, see the Build Skills with the Alexa Skills 
    Kit developer documentation: https://developer.amazon.com/docs/as
    k-overviews/build-skills-with-the-alexa-skills-kit.html.
    
...
    
DESCRIPTION
    Adds an Alexa::ASK::Skill resource to the template. The 
    Alexa::ASK::Skill resource creates an Alexa skill that enables 
    customers to access new abilities. For more information about 
    developing a skill, see the Build Skills with the Alexa Skills 
    Kit developer documentation: https://developer.amazon.com/docs/as
    k-overviews/build-skills-with-the-alexa-skills-kit.html.

Closing :)

[scrthq]

Awesome!!! Thanks again! ❤️

[scrthq]

https://vaporshell.io/docs/glossary/New-VSEC2VPCEndpointService

added bonus :D