Comment Based Help Keywords and Their Parameters Not Highlighting Correctly
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 3/5
- Thời gian dự kiến
- 1-2 ngày
- Mức phù hợp với người mới
- 38/100
- Loại issue
- Lỗi
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Đình trệ
- Công nghệ
- powershell
- Lĩnh vực
- tooling
Hướng nghiên cứu
Start in powershell.tmLanguage.json, focusing on the commentEmbeddedDocs captures and the existing .PARAMETER matching. Reproduce the provided comment-based help snippet in a supported editor, then compare highlighting for the listed keywords and parameters. Done means those keywords and valid parameters highlight consistently, with regression testing covering the behavior.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
Environment
- Editor and Version (VS Code, Atom, Sublime): VS Code 1.41.1
- OS: Windows 10
- PowerShell: 5.1
- Theme: Dark+
I tested the code snippet below with all extensions disabled using both the stable and preview versions of the PowerShell extension. In all cases the behavior was the same.
Issue Description
The following keywords and their parameters used in the Comment-Based-Help section of
a script or module not highlight correctly when compared to the other keywords that do not take parameters nor consistently when compared the .PARAMETER keyword.
.LINK
.FORWARDHELPTARGETNAME
.FORWARDHELPCATEGORY
.REMOTEHELPRUNSPACE
.EXTERNALHELP
The one keyword that does seem to at least partially work is the .PARAMETER keyword. It only highlights as a keyword if it has the required parameters and both the keyword and parameters highlight as the same type of syntax. (same color)
I was able to manually edit the powershell.tmLanguage.json file to get the highlighting to work but adjusting the moving all the keywords to the second "captures" under "commentEmbeddedDocs" and making some edits to the regex statement to include characters needed to create URI patterns.
When working against my local files I also created a new third "captures" group and moved the .FORWARDHELPCATEGORY to that group and added the regex to test for the list of valid categories that the keyword would take: (Alias|Cmdlet|HelpFile|Function|Provider|General|FAQ|Glossary|ScriptCommand|ExternalScript|Filter|All)
I don't have the knowledge to do the pull and edit XML and do the regression testing. I can test if someone is able to make the edits.
Screenshots


Expected Behavior
The keywords would highlight as comments if they did not have the required parameters (the ".PARAMETER" keyword is the only one that currently works) and the keywords and parameters would both highlight as keywords, as the ".PARAMETER" keyword and parameter does now or highlight as a keyword and parameter with two different colors.
Code Samples - Snippet:
function verb-noun {
<#
.SYNOPSIS
A brief description of the function or script.
This keyword can be used only once in each topic.
.DESCRIPTION
A detailed description of the function or script.
This keyword can be used only once in each topic.
.EXAMPLE
A sample command that uses the function or script, optionally followed by sample output and a description.
Repeat this keyword for each example.
.INPUTS
The Microsoft .NET Framework types of objects that can be piped to the function or script.
You can also include a description of the input objects.
.OUTPUTS
The .NET Framework type of the objects that the cmdlet returns.
You can also include a description of the returned objects.
.NOTES
Additional information about the function or script.
.COMPONENT
The technology or feature that the function or script uses, or to which it is related.
This content appears when the Get-Help command includes the Component parameter of Get-Help.
.ROLE
The user role for the help topic.
This content appears when the Get-Help command includes the Role parameter of Get-Help.
.FUNCTIONALITY
The intended use of the function.
This content appears when the Get-Help command includes the Functionality parameter of Get-Help.
.PARAMETER Inputs
The description of a parameter. Add a keyword for each parameter in the function or script syntax.
Type the parameter name on the same line as the keyword. Type the parameter description on the lines following the keyword.
Windows PowerShell interprets all text between the keyword line and the next keyword or the end of the comment block as part of the parameter description.
The description can include paragraph breaks.
The Parameter keywords can appear in any order in the comment block, but the function or script syntax determines the order in which the parameters (and their descriptions) appear in help topic.
To change the order, change the syntax.
You can also specify a parameter description by placing a comment in the function or script syntax immediately before the parameter variable name.
If you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored.
.LINK https://www.example.com/
The name of a related topic. The value appears on the line below the '.LINK' keyword and must be preceded by a comment symbol # or included in the comment block.
Repeat the keyword for each related topic. This content appears in the Related Links section of the help topic.
The keyword content can also include a Uniform Resource Identifier (URI) to an online version of the same help topic.
The online version opens when you use the Online parameter of Get-Help. The URI must begin with 'http' or 'https'.
.FORWARDHELPTARGETNAME Get-Help
Redirects to the help topic for the specified command.
You can redirect users to any help topic, including help topics for a function, script, cmdlet, or provider.
.FORWARDHELPCATEGORY All
Specifies the help category of the item in 'ForwardHelpTargetName'.
Valid values are 'Alias', 'Cmdlet', 'HelpFile', 'Function', 'Provider', 'General', 'FAQ', 'Glossary', 'ScriptCommand', 'ExternalScript', 'Filter', or 'All'.
Use this keyword to avoid conflicts when there are commands with the same name.
.REMOTEHELPRUNSPACE PSSessionVariable
Specifies a session that contains the help topic. Enter a variable that contains a 'PSSession'.
This keyword is used by the Export-PSSession cmdlet to find the help topics for the exported commands.
.EXTERNALHELP c:\external-Help.xml
Specifies an XML-based help file for the script or function.
The keyword is required when a function or script is documented in XML files.
Without this keyword, Get-Help cannot find the XML-based help file for the function or script.
The keyword takes precedence over other comment-based help keywords.
If present, Get-Help does not display comment-based help, even if it cannot find a help topic that matches the value of the keyword.
If the function is exported by a module, set the value of the keyword to a file name without a path.
Get-Help looks for the specified file name in a language-specific subdirectory of the module directory.
There are no requirements for the name of the XML-based help file for a function, but a best practice is to use the following format: <ScriptModule.psm1>-help.xml.
#>
[CmdletBinding()]
[OutputType([int])]
param(
[Parameter(Mandatory=true)]
[string]
Param1
)
begin {
}
process {
}
end {
Return ${Return}
}
}
- Ngôn ngữ chính
- PowerShell
- Star
- 151
- Fork
- 55
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của PowerShell/EditorSyntax
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 55/100
PowerShell/EditorSyntax#224 · 2 bình luận ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 48/100
PowerShell/EditorSyntax#222 · 2 bình luận ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 55/100
PowerShell/EditorSyntax#221 · 2 bình luận ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 45/100
PowerShell/EditorSyntax#220 · 2 bình luận · 1 reaction ·
-
Issue-Bug
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 48/100
PowerShell/EditorSyntax#219 · 2 bình luận ·
Tất cả issue của PowerShell/EditorSyntax
Issue tương tự
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
newrelic-experimental/preflight#793 · 1 bình luận ·
-
enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
babalae/bettergi-scripts-list#3674 ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
caddyserver/caddy#8046 ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
zilliztech/memsearch#759 ·
-
[Bug]: classify_items.py cron script never includes its own required JSON schema in the prompt Đang mởcomp/cron P2 sweeper:risk-automation type/bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
NousResearch/hermes-agent#117792 · 1 bình luận ·