Skip to content

multiple issues detecting documentation keywords #136

@msftrncs

Description

@msftrncs

Environment

  • Editor and Version: VS Code: 1.26.0 (with manual tweaks)
  • Your primary theme: Dark+

Issue Description

Presently, the documentation keyword detection/scoping/theming fails on the following items:

  • # .keyword doesn't detect and scope
  • <# .keyword doesn't detect and scope
  • once inside a comment block, extra # separated by spaces allows the keyword to detect, but Get-Help doesn't seem to permit this.
  • once inside a comment block, extra characters after a keyword that doesn't accept arguments allows the keyword to detect, but Get-Help doesn't seem to permit this.

Screenshots

image
(Showing modified sample from file attached to #134)

Expected Behavior

Expected to match Get-Help's acceptance. However, that's much more difficult. Get-Help also accepts:

  • <# #> # <additional #s> .keyword
  • does not accept .keyword if the containing comment doesn't otherwise start at the beginning of a line
  • and has limited acceptance of consecutively spaced and required placement, that probably only script analysis can accurately report on.

Possible Fix

I think two changes could fix the easiest problems.

  1. Change the match for 'commentEmbeddedDocs' to
    (#\1 match)
"(?:^|\G)(?i:\s*(\.)(COMPONENT|DESCRIPTION|EXAMPLE|EXTERNALHELP|FORWARDHELPCATEGORY|FORWARDHELPTARGETNAME|FUNCTIONALITY|INPUTS|LINK|NOTES|OUTPUTS|REMOTEHELPRUNSPACE|ROLE|SYNOPSIS))(?:\s*$)"
(#\2 Match)
"(?:^|\G)(?i:\s*(\.)(PARAMETER|FORWARDHELPTARGETNAME|FORWARDHELPCATEGORY|REMOTEHELPRUNSPACE|EXTERNALHELP)\s+([a-z0-9-_]+))"
  1. Change 'begin' match for 'commentLine' to
"(?<![`\\-])(#)#*"

and change the capture from "0" to "1".

With the changes applied, this is the result:

image
(not necessary valid, I know)

# .synopsis
<# .synopsis
.synopsis
<#
# ## ## .DESCRIPTION blah blah
    This is a script function that will install HealOps on "X" system.
#>

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions