{"id":7172,"date":"2014-04-16T11:56:00","date_gmt":"2014-04-16T19:56:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=7172"},"modified":"2014-04-16T11:57:15","modified_gmt":"2014-04-16T19:57:15","slug":"powershell-studio-2014-comment-based-help","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2014\/04\/16\/powershell-studio-2014-comment-based-help\/","title":{"rendered":"PowerShell Studio 2014: Comment Based Help"},"content":{"rendered":"<p>Previously, when creating comment based help in PowerShell Studio 2012, you either had to manually add the help comment or use the built-in comment based help snippet. The snippets worked well but you were still required to manually add each parameter of the function which takes time and there are better ways we would rather spend our time than writing help comments. <\/p>\n<p>One of the new features we added into PowerShell Studio 2014 is the capability to automatically generate comment blocks for existing functions. You can generate comment base help for an existing function by:<\/p>\n<p>1. Using the function explorer\u2019s context menu:<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" title=\"image\" style=\"border-left-width: 0px; border-right-width: 0px; border-bottom-width: 0px; display: inline; border-top-width: 0px\" border=\"0\" alt=\"image\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image.png\" width=\"265\" height=\"223\"> <\/p>\n<p>2. Using the editor. Right click on the function\u2019s declaration or the param keyword and bring up the context menu:<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" title=\"image\" style=\"border-left-width: 0px; border-right-width: 0px; border-bottom-width: 0px; display: inline; border-top-width: 0px\" border=\"0\" alt=\"image\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image1.png\" width=\"555\" height=\"227\"> <\/p>\n<p>&nbsp;<\/p>\n<p><em>Generate Comment Base Help<\/em> command will insert a help comment tailored to the specific function. The comment will include a .PARAMETER entry for each parameter declared in the function, include an .EXAMPLE entry and add any applicable output entry: <\/p>\n<p><a href=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image2.png\"><img loading=\"lazy\" decoding=\"async\" title=\"image\" style=\"border-left-width: 0px; border-right-width: 0px; border-bottom-width: 0px; display: inline; border-top-width: 0px\" border=\"0\" alt=\"image\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image_thumb.png\" width=\"244\" height=\"234\"><\/a> <\/p>\n<p>You will still need to supply the descriptive text (it can\u2019t do everything for you) but the structure is there for you to update and edit. <\/p>\n<p>If needed, you can expand on the help comment with the help of PowerShell Studio 2014\u2019s PrimalSense:<\/p>\n<p><a href=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image3.png\"><img loading=\"lazy\" decoding=\"async\" title=\"image\" style=\"border-left-width: 0px; border-right-width: 0px; border-bottom-width: 0px; display: inline; border-top-width: 0px\" border=\"0\" alt=\"image\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image_thumb1.png\" width=\"644\" height=\"199\"><\/a> <\/p>\n<p>&nbsp;<\/p>\n<p>At one point, you may add a new parameter to an existing function and need to update the help comment. By calling <em>Generate Help Comment <\/em>again, it will take any existing help comment and append any missing parameters to the comment block:<\/p>\n<p><a href=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image4.png\"><img loading=\"lazy\" decoding=\"async\" title=\"image\" style=\"border-left-width: 0px; border-right-width: 0px; border-bottom-width: 0px; display: inline; border-top-width: 0px\" border=\"0\" alt=\"image\" src=\"http:\/\/www.sapien.com\/blog\/wp-content\/uploads\/2014\/04\/image_thumb2.png\" width=\"244\" height=\"151\"><\/a> <\/p>\n<p>&nbsp;<\/p>\n<p>We hope that this new feature will help users save time and promote the use of help comments in their script.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Previously, when creating comment based help in PowerShell Studio 2012, you either had to manually add the help comment or use the built-in comment based help snippet. The snippets worked well but you were still required to manually add each parameter of the function which takes time and there are better ways we would rather [&hellip;]<\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[703,632,25],"tags":[904,28,874,141],"class_list":["post-7172","post","type-post","status-publish","format-standard","hentry","category-powershell-studio","category-whats-new-software-news","category-windows-powershell","tag-comment-based-help","tag-powershell","tag-powershell-studio-2014","tag-whats-new"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/7172","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=7172"}],"version-history":[{"count":7,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/7172\/revisions"}],"predecessor-version":[{"id":7211,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/7172\/revisions\/7211"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=7172"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=7172"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=7172"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}