Wednesday, May 18, 2016

Visual Studio POSH snippet, DocuComment

I am trying to get into more Visual Studio (as that is what "real" programmers use).... and to my delight, I found out that PowerShell is more supported than ever before in VS 2015.  Perhaps I can finally put away my childish things (ISE) and move onto something much more unnecessarily complicated.   So when I read about "code snippets" I was excited... but....

 No matter how much I searched, I could not find one for a simple "documentation block."  You know, the one with the ".Synopsis", and ".Example" that we are supposed to use in our scripts, but never do?  Perhaps I can make the world a better place by figuring it out and allowing others to use it.  Now you have no excuse to not document your code better, you are just three clicks away from having the "DocuComment" block created for you!

You will need to put the code below in to a file with an extension of ".snippet" and import it into VS.
(Details of this can be found at: https://msdn.microsoft.com/en-us/library/9ybhaktf(v=vs.100).aspx )

DocuComment.snippet :

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets  xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>DocuComment Block</Title>
      <Shortcut>docucomment</Shortcut>
      <Description>Code snippet for a comment block.</Description>
      <Author>Bryan Loveless bryan.loveless@gmail.com</Author>
      <SnippetTypes>
        <SnippetType>Expansion</SnippetType>
        <SnippetType>SurroundsWithStatement</SnippetType>
      </SnippetTypes>
    </Header>
    <Snippet>
      <Declarations>
        <Literal>
          <ID>param1</ID>
          <ToolTip>DocuComment</ToolTip>
          <Default>
            .SYNOPSIS

            synopsis of script, overall idea



            .DESCRIPTION

            description of overall script, more detail than synopsis



            .PARAMETER parameternamehere

            parameter description, if required, possible values



            .PARAMETER path

            parameter path



            .EXAMPLE

            example of script use, return behavior.



            .EXAMPLE

            another exmample if there are more.  This can be repeated for as many examples as you want



            .NOTES

            other misc notes, perhaps permissions needed, dates of script.
          </Default>
        </Literal>
      </Declarations>
      <References />
      <Code Language="PowerShell">
        <![CDATA[<#
$param1$
$selected$ $end$
#>]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

No comments:

Post a Comment