and yet again another feature-request-bundle, this time all about CBH.
Writing CBH: Indentation Hell
Frankly, writing CBH is a bit of a pain in PSS. Even Notepad++ is better at it.
Text won't honor the default indentation, so for each segment I have to redo indents manually.
Assuming a default function file, on pressing "Enter" the cursor will move to the default level of indentation of the code surrounding the help, even if the previous lines was indented three levels.
Assuming the "|" is the cursor, I'll now be thrown back to the first level, because inside the function we've got by default a single level of indentation.
Code: Select all
A brief description of the Get-Test function.
A detailed description of the Get-Test function.
PS C:\> Get-Test
Additional information about the function.
Instead it should be on the same level as the text of the previous line.
It may be a minor nuisance, but it really adds up.
Another thing that would be nice would be options to configure indentation levels for CBH:
- Base Indentation (Where the '<#' and '#>' start)
- Header Indentation (Where '.PARAMETER', '.SYNOPSIS', '.NOTES', ... start)
- Content Indentation (Where the actual content starts)
With these settings being honored by both the editor as well as the script formatter.
Add a function that scans a file/project and:
- Removes surplus parameter help
- Adds missing parameter help
- Reports bad header names (e.g.: Typos such as '.PARAMTER')
This could be handled with a GUI similar to rename with the ability to preview changes, apply them all or one by one, adding missing content
Project wide Parameter help
A functionality that updates the help for a given parameter name over an entire project. Often we have the same parameter in lots of functions. Be it $ComputerName, $SqlInstance, $Silent or whatever. Being able to globally set the help for them would be an aid in maintaining project-wide uniformity.
Automatically add CBH for -Confirm and -WhatIf
Functions that support ShouldProcess are granted two additional parameters but not their help (in opposite to the other common parameters). Thus these need to receive CBH entries in order for their help to show.
It would be awesome if your "Generate CBH" functionality would also add those if the function does implement ShouldProcess (can be read from the Cmdletbinding). Maybe also add a default text for them with a way for the user to change it (possibly using he template system).