Generated Help

[jdhitsolutions]

I thought this could start as a discussion before filing an issue because this may be more of a preference thing. In the generated psm1 file, the comment-based help is stuck right after the Process block.

  } # end PROCESS

<#
.SYNOPSIS
Get entries from CmdKey

.DESCRIPTION
Get Cmdkey Entries

.PARAMETER List
List cmdkey entries for the specified computer. Wildcards are permitted.

I'd rather see it inserted immediately after the Function Verb-Noun { line. I'm thinking that eventually, I'll use Platyps to generate the final help at which point I'd like to be able to easily delete the comment block from the file.

[tommymaynard]

I'd rather see it inserted immediately after the Function Verb-Noun...

I agree with this, 100%! It's where I place my comment-based help.

[theJasonHelmick]

Thanks @jdhitsolutions -- Thanks for the suggestion and including your thoughts about using PlatyPS. I hadn't considered that scenario. This hasn't been top of our priority list, but you raise an important point. For maintainability (or easy deletion in your case) does it really matter if it's before, inside, or after the function? The reason I'm asking is that different people have different preference about the location in file of comment based help. For instance, I avoided putting the help after the function line as it visually breaks up the function . I'm certainly open to the discussion and everyones views on changing this. Let's discuss and then can raise an issue if warranted.

[jdhitsolutions]

The layout should be

Function Get-Awesome {
 <# help

 [cmdletbinding()]
Param()
  Begin {}
  Process {}
  End {}
}

This is the way I see most code. And to my mind, it makes the most sense for someone maintaining code. If someone gave me a piece of code, it is much easier to open the file and first read the help to get some background. Then as I read the code I have a better idea about what is supposed to happen. I don't consider it breaking up the function, I consider it part of the function.