September 8, 2020 at 7:00 am #255251ParticipantTopics: 2Replies: 0Points: -8Rank: Member
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:
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.
So, I set out to test if this is indeed the case.
This is the tiny test help within my test function:<#.SYNOPSISRetrieve jobs from Splunk..DESCRIPTIONRetrieves jobs via Splunk REST API..ROLESplunkAPI.FUNCTIONALITYGetSplunkSearch#>After having forcefully imported the module again, I run the following cmdlet to test my theory:Get-Help -Role SplunkAPIAnd 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 GetSplunkSearchNow, 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”:<#.SYNOPSISRetrieve jobs from Splunk..DESCRIPTIONRetrieves jobs via Splunk REST API..ROLESplunk API.FUNCTIONALITYRetrieves search jobs from Splunk via REST API.#>
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 2 months, 2 weeks ago by Ramil Rohi. Reason: Formatting issue
- You must be logged in to reply to this topic.