[PSS 2017] Writing and formatting CBH

Post feature requests, product enhancement ideas, and other product-specific suggestions here. Do not post bug reports.
Forum rules
Do not post any licensing information in this forum.
Posts: 289
Last visit: Sun Jan 24, 2021 2:18 am

[PSS 2017] Writing and formatting CBH

Post by Bosparan »


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.
  1. function Get-Test
  2. {
  3.     <#
  4.         .SYNOPSIS
  5.             A brief description of the Get-Test function.
  7.         .DESCRIPTION
  8.             A detailed description of the Get-Test function.
  10.         .PARAMETER Foo
  11.             Bar|
  13.         .EXAMPLE
  14.             PS C:\> Get-Test
  16.         .NOTES
  17.             Additional information about the function.
  18.     #>
  19.     [CmdletBinding()]
  20.     Param (
  21.         $Foo
  22.     )
  23. }
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.
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.

Configuring Indentation
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.

Repairing CBH
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).