AutoHelp with Get-Help and Advanced Functions - needs improving
Votes from Connect: 13
Original Date Submitted: 12/27/2008 11:39:54 PM
Site Name: PowerShell
Feedback ID: 389767
Frequency: Always Happens
Regression: No, this is new to the most recent version
I think the new auto-help stuff is fantastic. But it's a tad buggy and inconsistent.
To demonstrate this, I've created a simle advanced function file (get-autohelp.ps1) attached. You will need to save this file then run get-help against it to see the errors I note.
Here are the issues:
You can not specify a .NAME section in auto-help. If you do, then the output returned by get-help is heaviliy truncated. You should enable the developer to specify a name section, with Get-Help then supplementing this with the file name that the script lived in.
Two sections change name from script file to output by Get-Help. The ".DESCRIPTIION" section becomes "Detailed Description" in get-help output. And .LINK befomes "RELATED LINKS. This is inconsistent. Either make Get-Help produce the section names in the file, or change what sections you can specify in the file to match what get-help produces.
.LINK links are shown in basic get-help output, and with -FULL, but not -Detailed. This is inconsistent - anything shown in basic output should be shown with -full or -detailed.
It's not clear how to use .COMPONENT, .ROLE and .FUNCTIONALITY sections. These do not appear to be output in any use of get-help. If nothing else, there needs to be more details on these sections.
Product Studio item created by Connect Synchronizer due to creation of feedback ID 389767 (http://connect.microsoft.com/feedback/ViewFeedback.aspx?SiteID=99&FeedbackID=389767).
1. Take Get-AutoHelp.ps1 from bug report and save it.
2. To see issue 1, add a section:
before line 2 in attached script. Run Get-Help, Get-Help -full, Get-Help -Detailed against the script, then do it again with these lines removed.
Run Get-Help, Get-Help -full, Get-Help-Detailed to see the first three issues.
Run get-help -role *, get-help-component * to see issue
1. Ability to specify a name
2. Consistency of section names to get-help output
3. Ability to use .COMPONENT, .ROLE, and .FUNCTIONALITY sections
Internal BugId: 1838