feature(magicpacket): add comment-based help

- add help text
- include examples
- add pipeline assistance text
- clean-up code format

wol-magicPacket.psm1

@@ -1,10 +1,55 @@
+<#
+.SYNOPSIS
+Broadcast one or more "magic packets" across a subnet to wake-up one or more target computers.
+
+.DESCRIPTION
+Sends a configurable number of "magic packets" per supplied MAC address as a broadcast over the subnet using a specified UDP port. MAC addresses can be supplied directly or via the pipeline either with or without explicitly specifying a parameter. The broadcast address and UDP port can be specified via parameters.
+
+Note: You must specify the '-Verbose' parameter to see output for successfully sent packets.
+
+.PARAMETER MacAddress
+Array of MAC addresses for which to construct magic packets. The array should be provided in standard comma-separated string format ('1a:2a:3a:4a:5a:aa', '1b:2b:3b:4b:5b:bb', ...). You may use either a colon (:) or a hyphen (-) to delimit each hex value-pair in the MAC address. You may supply this array either directly or via the pipline.
+
+.PARAMETER BroadcastIP
+The address to which magic packets should be sent in order for them to be broadcast across the subnet. By default this is 255.255.255.255 however, many routers block such global broadcasts. Therefore, it is suggested to use the subnet-specific broadcast address (e.g. 192.168.1.255). You may also use IP6 addresses if you prefer.
+
+.PARAMETER Port
+The UDP port that should be used when sending the broadcast. By default this is port 7 (echo). Port 9 (discard) is also a common port.
+
+.INPUTS
+String array or object containing a string array named "MacAddress".
+
+.EXAMPLE
+Send-MagicPacket 1a-2a-3a-4a-5a-aa
+Wake-up a computer with MAC address '1a-2a-3a-4a-5a-aa' via global broadcast using default port (echo).
+
+.EXAMPLE
+Send-MagicPacket '1a-2a-3a-4a-5a-aa' 192.168.1.255 9
+Wake-up a computer with MAC address '1a-2a-3a-4a-5a-aa' in subnet 192.168.1.0/24 using port 9 (discard).
+
+.EXAMPLE
+Send-MagicPacket -MacAddress '1a-2a-3a-4a-5a-aa', '1b-2b-3b-4b-5b-bb', '1c:2c:3c:4c:5c:cc' -Port 99 -BroadcastIP 10.0.1.255 -Verbose
+Wake-up 3 computers in the specified subnet using non-standard port. Parameters are explicitly defined. Show confirmation messages for each MAC address.
+
+.EXAMPLE
+'1a-2a-3a-4a-5a-aa', '1b-2b-3b-4b-5b-bb' | Send-MagicPacket -IP 172.16.20.255 -Verbose
+Use pipeline to provide MAC addresses, provide broadcast address directly. Show result.
+
+.NOTES
+There is no output generated for successfully sent packets. This is done to keep the pipeline clear. To see success confirmation messages, run this function with the '-Verbose' parameter.
+#>
 function Send-MagicPacket
 {
     [CmdletBinding()]
     param
     (
     # Array of MAC addresses for which to construct magic packets
-        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [Parameter(
+                Mandatory,
+                ValueFromPipeline,
+                ValueFromPipelineByPropertyName,
+                HelpMessage = "Please provide one or more MAC addresses. You may use a colon (:) or a hypen (-) to separate hex values."
+        )]
         [ValidatePattern('^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$')]
         [String[]]
         $MacAddress,