PowerShell / PowerShell/PSScriptAnalyzer

Warn on syntax that will cause comment-based help to fail to be discovered/usable

Đang mở
#500 8 bình luận 1 reaction 1 người được giao Xem trên GitHub

@kapilmb đang làm issue này rồi.

Từ ngày 23/4/2016.

Issue - Discussion Issue - New Rule Up-for-Grabs
Ngôn ngữ chính
C#
Star
2.2k
Fork
414
Merge trung bình
13 giờ 1 phút
Pull request đã merge (30 ngày)
2

Mô tả

Related to this item on UserVoice:
https://windowsserver.uservoice.com/forums/295047-general-feedback/suggestions/13383489-show-syntax-errors-in-powershell-comment-based-hel

Today comment-based help is very fragile, and there are multiple ways you can do something with it that will cause the help to fail to load in PowerShell. PowerShell would do well to report a warning when such a failure is discovered, but that change would only happen in PSvLatest, while a PSScriptAnalyzer rule would resolve this for PSv3+, so I'd like to see this improved with a new rule in PSScriptAnalyzer.

Here are the issues I have noticed people mention so far:

Invalid (mispelled, incorrect) comment-based help keywords.
e.g. The incorrect
.DESCIPRITION
vs the correct
.DESCRIPTION
Note for this issue, that includes starting a line with a period, such as ".NET Framework". The parsing logic should split on lines that start with period and warn if any line keywords don't match up with what is in the comment-based help keyword list.

Incorrect placement of comment-based help keyword values.
e.g. The incorrect
.PARAMETER
<parameter_name>
vs. the correct
.PARAMETER <parameter_name>
The parsing logic should verify the syntax for each keyword.

Spaces between comment-based help and a function, when placing it outside of a function.
e.g. The incorrect
<#
.SYNOPSIS
whatever

>

function Test-CommentBasedHelp {}
vs the correct
<#
.SYNOPSIS
whatever

>

function Test-CommentBasedHelp {}
(NOTE: I'm reporting this one because I saw others mention it but I could not reproduce it using 5.0.10586.122, so maybe this applies only to earlier versions of PowerShell? Some testing is required to nail this one down -- see the discussion point below)

These are only a few examples. I think it would be good to mark this as Discussion and then let others share specific issues they have run into with comment-based help, and then address them with a rule in PSScriptAnalyzer that watches script authors' backs in this area.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. 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.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.