PowerShell help – The lesser known keywords

Welcome Forums Non-Technical Discussions Teaching PowerShell PowerShell help – The lesser known keywords

Viewing 0 reply threads
  • Author
    Posts
    • #255251
      Participant
      Topics: 2
      Replies: 0
      Points: 12
      Rank: Member

      Hello!

      Intro

      I had a revelation today when searching for what’s the purpose of .FUNCTIONALITY and .ROLE keywords when writing help for my functions. My search ended up here, where two members were discussing about the very same thing:

      https://powershell.org/forums/topic/what-is-the-use-of-functionality-parameter-in-help/

      To be honest, the Microsoft’s explanation is very vague: about_comment_based_help, all you can do is guess how and if this would be of any use for you.

      So, after having used PowerShell for many years, written a couple of modules with full help, I had an idea today.. what if the role and functionality are actually keywords, instead of some descriptive text telling users what the role and functionality of the function is.

      Hands-on

      So, I set out to test if this is indeed the case.

      This is the tiny test help within my test function:

      <#
      .SYNOPSIS
      Retrieve jobs from Splunk.
      .DESCRIPTION
      Retrieves jobs via Splunk REST API.
      .ROLE
      SplunkAPI
      .FUNCTIONALITY
      GetSplunkSearch
      #>
      After having forcefully imported the module again, I run the following cmdlet to test my theory:
      Get-Help -Role SplunkAPI
      And indeed, I got my cmdlet that has this specific role assigned to it.
      And this could be combined with Functionality parameter, to further drill down the search:
      Get-Help -Role SplunkAPI -Functionality GetSplunkSearch
      Now, this might seems pointless within a single module, but if you would have different modules, or different module maintainers, covering similar roles, or functionalities. In a larger scenario, this would help a user find cmdlets covering a specific role, or functionality. Given that module maintainers have made the roles and functionalities available for the end-user, otherwise the user would be forced to shift through the code, since none of the Get-Help parameters (Full, Detailed) show the roles and functionalities within the module. Also, the different developers would have to abide a agreed upon naming scheme. Having role, or functionality keywords differ will make this a bit useless. For example: SplunkAPI, SplunkREST, SplunkRESTAPI.

      Here’s an example how I used to think the role and functionality keywords “work”:

      <#
      .SYNOPSIS
      Retrieve jobs from Splunk.
      .DESCRIPTION
      Retrieves jobs via Splunk REST API.
      .ROLE
      Splunk API
      .FUNCTIONALITY
      Retrieves search jobs from Splunk via REST API.
      #>

      Conclusion

      After having used PowerShell for a long time, daily, and not knowing about that, I’m sure there are other people out there who are running against the same problem and end up not using them.. for the wrong reasons.

      I myself have to go over some of my older modules and make some corrections.

      • This topic was modified 1 week, 5 days ago by Ramil Rohi. Reason: Formatting issue
Viewing 0 reply threads
  • You must be logged in to reply to this topic.