- Now that I'm designing my script
for someone else to use,
it'd be awfully nice if I gave them some help.
Now, you can always put comments into your scripts.
There's a pound sign character.
Notice how the colors turn green
and you can put in "Main Code here."
You can always put in comments.
Also, let me just show you,
you can also put in block comments, as well.
Let me hit a few Enters here.
Here's block comments,
angle bracket and a hash,
and then, there.
And inside, you can now type
whatever it is you wanna type.
The parsing engine doesn't look at your comments,
so it doesn't affect your code.
Did I just say
"the parsing engine doesn't look at your comments"?
Yeah, I did.
And here's something kind of interesting.
If you do what PowerShell wants you to do,
it'll make your life easier.
Let me give you an example.
Right now, I've got this.
If I do get-help on DiskInfo,
it's starting to build out the syntax already for me.
That's because I'm doing things
the way that PowerShell wants me to do them.
I used that param keyword.
It read it and it knows
how to start to turn that into syntax.
Here's the interesting part:
I can continue doing what PowerShell wants me to do
and it will help me.
Rather than manually trying to create a bunch of help files,
I'm going to use something called comment-based help.
I'll show you where to look this up
so that you can get the details on it.
But let me just give you a quick example.
Synopsis
This ...
And my typing is not intentionally necessarily
going to be the greatest.
"This is brief comments,"
and I'll do .Description.
"This is the long comments."
I'll do .Parameter.
With parameter, let's do it ComputerName.
"This is the name
"of a remote computer."
And let's do an example.
Example.
DiskInfo
- computername
localhost.
And one more example.
Example.
"Connecting to remote computers,"
and we'll do DiskInfo
- computername,
and I'm just gonna put in DC.
Now, I want you to notice that I've made some comments
with some very specific ...
Well, special characters.
What I've done is this.
See the ones with the dots?
This tells PowerShell something special.
The parsing engine actually
can read these special dot.
And what it does is ...
Well, let me show you what it does.
I'm gonna save this.
You'll see it right away.
Look.
I have a great, now, looking help file.
PowerShell just built for me
the entire help file.
Look.
The name, the synopsis,
it's building the syntax, the description ...
And I didn't have to work very hard for it.
Now, this is just the basic help.
I'm gonna clear the screen,
and when I run help,
remember, with help I can do detailed help.
That would give me the examples,
and there's all the examples.
So if I do what PowerShell wants me to do,
in other words, the way that it can read things,
it's gonna help me build this great help file.
This is what you want to do when you make a tool
and you can see how straightforward and simple this is.
Now, a couple of warning things when you try this.
These are very specific.
I'm gonna show you where you can find the list of them.
There's additional ones that you can add,
but in case you forget,
you can always find this.
It's in the help system.
Also, you gotta be careful here.
Notice where the word "param" begins,
and where this help file ends.
You can have one space in there,
but you can't have two or it'll break
and it won't work correctly.
So if you can't get your help to work,
that's one of the first things to look at.
Then also check the spelling of these.
And let me show you
where you can find out more information
about building the help file.
If you do get-help on about_ ...
And this is referred to as Comment_Based_Help.
I'm gonna go strike enter
and it's just gonna scrolling across the screen,
but this breaks down all of the help
that you can create inside of there.
Here's the general rule
that we like to follow:
If you're gonna make a parameterized script
for somebody else,
even for just yourself,
since you're gonna probably forget
exactly how it works in a few weeks,
always create help.
It doesn't take that much longer,
and this is a very professional way to do it.
It makes it look just like a commandlets help.
In fact, kind of a sidebar,
just to let you know:
from this point, you can turn this into a commandlet.
You can then put a bunch of commandlets
into your own module.
So you can do the same thing that Microsoft does,
make commandlets and make modules
from this point going forward.
Those are known as advanced functions.
The word is advanced,
but it's not much more complicated
than what we've done here.
There are help files on those.
Let's go ahead and end this sidebar there.
But you can certainly go further.
Now, this is a parameterized script.
What I do is,
notice I solved the problem first.
I solved it in the shell.
Once the problem is solved the way that I want,
I parameterized the things I wanted to be able to change,
and then I gave it help.