Add Snippet for Documentation

[bcrotty]

We should add a snippet for documentation. https://technet.microsoft.com/en-us/magazine/ff458353.aspx is the closest I found to a published standard.

Their example is:

<#

.SYNOPSIS

Retrieves service pack and operating system information from one or more remote computers.



.DESCRIPTION

The Get-Inventory function uses Windows Management Instrumentation (WMI) toretrieve service pack version, operating system build number, and BIOS serial number from one or more remote computers. 

Computer names or IP addresses are expected as pipeline input, or may bepassed to the –computerName parameter. 

Each computer is contacted sequentially, not in parallel.



.PARAMETER computerNameAccepts 

a single computer name or an array of computer names. You mayalso provide IP addresses.



.PARAMETER path

The path and file name of a text file. Any computers that cannot be reached will be logged to this file. 

This is an optional parameter; if it is notincluded, no log file will be generated.



.EXAMPLE

Read computer names from Active Directory and retrieve their inventory information.

Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.



.EXAMPLE 

Read computer names from a file (one name per line) and retrieve their inventory information

Get-Content c:\names.txt | Get-Inventory.



.NOTES

You need to run this function as a member of the Domain Admins group; doing so is the only way to ensure you have permission to query WMI from the remote computers.

#>

[bcrotty]

I agree with @guillermooo on keeping the snippets limited and basic. We don't want to add a bunch that will be coming up as people type. The one (non basic) snippet I would really like to add is one for the beginning script documentation (synopsis, description, parameters, etc). I think this will help encourage better documented code. @guillermooo and @vors, what do you think?

[vors]

I like this idea. How it should be triggered? <# . ?

[bcrotty]

That works, or would something like docu be easier?

[vors]

As I said, I don't use snippets (which I probably should start right now), so I don't have any strong opinion. Maybe help, since this comments consumed by Get-Help?

[guillermooo]

Requirements:

• should only trigger in source.dart scope (for example, not inside a string)

I don't know what a good name would be, but I favor abbreviations that are close to but not always exactly real words. Specially so if the snippet is complex. This has the advantage, in my opinion, that you have to intentionally type the abbreviation to get the snippet instead of ST inserting a whole lot of text out of nowhere. For example, in Python there's a prop or property snippet that inserts a complex template that's a nuisance more often than not.

With that said, any of these are ok with me:

• docc (for doc comment)
• comm (for comment)
• help
• ## (I don't think this is technically possible?)

In any case, as a general rule I wouldn't have more than three $n fields for cycling through regardless of the snippet's length. More than three and you forget where you are in the snippet while cycling through.

Also, another mnemonic I use is: the longer the snippet, the longer its trigger. For example, i inserts a json item for me in one context, while ii inserts a longer version of the same item. Not saying we should go this way, just offering more options!

[bcrotty]

Sounds good. I'll work on pulling this together and we can discuss more once it's created. Thanks!