Author Posts

January 1, 2012 at 12:00 am

by stromnessian at 2013-02-26 00:14:00

Hi

Just a couple of questions about comment-based help:

1. In the about_Comment_Based_Help help topic:
[quote]All of the lines in a comment-based help topic must be contiguous.[/quote]
Does this only apply to single comment lines, as opposed to comment blocks? I've inserted multiple blank lines into my comment-based help in a comment block and it still seems to work fine.

2. In Learn PowerShell Toolmaking in a Month of Lunches:
[quote]For the first function in your script file, however, make sure there is no more than one blank line between the end of the comment-based help block and the function keyword. Also, there must be at least two blank lines between the start of the script and the first line of the comment-based help. Otherwise, the help will be interpreted as being for the script rather than for the function.[/quote]
In my experience, I haven't had to insert "two blank lines between the start of the script and the first line of the comment-based help" to get it to work.

Best regards

by DonJ at 2013-02-26 09:42:17

Having a blank line in the help is fine so long as it's a comment:


# This
#
# Is Fine

But


# This

# Is not

The book quote is a bit out of context. The deal is this: If your comment-based help is INSIDE the function declaration, you're fine. If the comment-based help is OUTSIDE the function declaration, and there aren't a couple of blank lines before it, then the help is interpreted as help for the SCRIPT FILE, not the function. This is described in about_comment_based_help. If you're not writing a function, and you just want comment-based help for a script file, then you don't need the blank lines because that's how it will interpret it anyway.

by stromnessian at 2013-02-26 13:32:34

Thanks for clearing that up Don. Great book series btw 🙂