Skip to content

Update documentation #704

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 7, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Table of Contents

<!-- tocstop -->

Introduction
Introduction [&uarr;](#table-of-contents)
============
PSScriptAnalyzer is a static code checker for Windows PowerShell modules and scripts. PSScriptAnalyzer checks the quality of Windows PowerShell code by running a set of rules.
The rules are based on PowerShell best practices identified by PowerShell Team and the community. It generates DiagnosticResults (errors and warnings) to inform users about potential
Expand All @@ -41,15 +41,16 @@ code defects and suggests possible solutions for improvements.
PSScriptAnalyzer is shipped with a collection of built-in rules that checks various aspects of PowerShell code such as presence of uninitialized variables, usage of PSCredential Type,
usage of Invoke-Expression etc. Additional functionalities such as exclude/include specific rules are also supported.

Usage

Usage [&uarr;](#table-of-contents)
======================
``` PowerShell
Get-ScriptAnalyzerRule [-CustomizedRulePath <string[]>] [-Name <string[]>] [<CommonParameters>] [-Severity <string[]>]

Invoke-ScriptAnalyzer [-Path] <string> [-CustomizedRulePath <string[]>] [-ExcludeRule <string[]>] [-IncludeRule <string[]>] [-Severity <string[]>] [-Recurse] [<CommonParameters>]
```

Installation
Installation [&uarr;](#table-of-contents)
============

### From PowerShell Gallery
Expand All @@ -75,7 +76,7 @@ Exit
### From Source

#### Requirements
* .Net Core
* [.NET Core 1.0 SDK Preview 2](https://github.com/dotnet/core/blob/master/release-notes/download-archives/1.0-preview2-download.md)
* [PlatyPS 0.5.0 or greater](https://github.com/PowerShell/platyPS)

#### Steps
Expand All @@ -89,6 +90,10 @@ Exit
```powershell
cd path/to/PSScriptAnalyzer
```
* Restore packages
```powershell
dotnet restore
```
* Build for your platform
* Windows PowerShell version 5.0 and greater
```powershell
Expand Down Expand Up @@ -130,7 +135,7 @@ cd /path/to/PSScriptAnalyzer/Tests/Rules
Invoke-Pester
```

Suppressing Rules
Suppressing Rules [&uarr;](#table-of-contents)
=================

You can suppress a rule by decorating a script/function or script/function parameter with .NET's [SuppressMessageAttribute](https://msdn.microsoft.com/en-us/library/system.diagnostics.codeanalysis.suppressmessageattribute.aspx).
Expand Down Expand Up @@ -215,7 +220,7 @@ Param()

**Note**: Rule suppression is currently supported only for built-in rules.

Settings Support in ScriptAnalyzer
Settings Support in ScriptAnalyzer [&uarr;](#table-of-contents)
========================================
Settings that describe ScriptAnalyzer rules to include/exclude based on `Severity` can be created and supplied to
`Invoke-ScriptAnalyzer` using the `Setting` parameter. This enables a user to create a custom configuration for a specific environment. We support the following modes for specifying the settings file.
Expand Down Expand Up @@ -264,7 +269,7 @@ Invoke-ScriptAnalyzer -Path "C:\path\to\project" -Recurse

Note that providing settings explicitly takes higher precedence over this implicit mode. Sample settings files are provided [here](https://github.com/PowerShell/PSScriptAnalyzer/tree/master/Engine/Settings).

ScriptAnalyzer as a .NET library
ScriptAnalyzer as a .NET library [&uarr;](#table-of-contents)
================================

ScriptAnalyzer engine and functionality can now be directly consumed as a library.
Expand All @@ -288,7 +293,7 @@ public System.Collections.Generic.IEnumerable<DiagnosticRecord> AnalyzePath(stri
public System.Collections.Generic.IEnumerable<IRule> GetRule(string[] moduleNames, string[] ruleNames)
```

Violation Correction
Violation Correction [&uarr;](#table-of-contents)
====================
Most violations can be fixed by replacing the violation causing content with the correct alternative.

Expand Down Expand Up @@ -334,7 +339,7 @@ The main motivation behind having `SuggestedCorrections` is to enable quick-fix
* MissingModuleManifestField.cs
* UseToExportFieldsInManifest.cs

Project Management Dashboard
Project Management Dashboard [&uarr;](#table-of-contents)
==============================
You can track issues, pull requests, backlog items here:

Expand All @@ -348,7 +353,7 @@ Throughput Graph

[![Throughput Graph](https://graphs.waffle.io/powershell/psscriptanalyzer/throughput.svg)](https://waffle.io/powershell/psscriptanalyzer/metrics)

Contributing to ScriptAnalyzer
Contributing to ScriptAnalyzer [&uarr;](#table-of-contents)
==============================
You are welcome to contribute to this project. There are many ways to contribute:

Expand All @@ -369,6 +374,6 @@ You might also read these two blog posts about contributing code: [Open Source C

Before submitting a feature or substantial code contribution, please discuss it with the Windows PowerShell team via [Issues](https://github.com/PowerShell/PSScriptAnalyzer/issues), and ensure it follows the product roadmap. Note that all code submissions will be rigorously reviewed by the Windows PowerShell Team. Only those that meet a high bar for both quality and roadmap fit will be merged into the source.

Code of Conduct
Code of Conduct [&uarr;](#table-of-contents)
===============
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
1 change: 1 addition & 0 deletions RuleDocumentation/PlaceCloseBrace.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Close brace placement should follow a consistent style. It should be on a new li
Enable = $true
NoEmptyLineBefore = $false
}
}
```

### Parameters
Expand Down
1 change: 1 addition & 0 deletions RuleDocumentation/PlaceOpenBrace.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Open brace placement should follow a consistent style. It can either follow KR s
OnSameLine = $true
NewLineAfter = $true
}
}
```

### Parameters
Expand Down
3 changes: 2 additions & 1 deletion RuleDocumentation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,4 +49,5 @@
|[UseCompatibleCmdlets](./UseCompatibleCmdlets.md) | Warning|
|[PlaceOpenBrace](./PlaceOpenBrace.md) | Warning|
|[PlaceCloseBrace](./PlaceCloseBrace.md) | Warning|
|[UseConsistentIndentation](./UseConsistentIndentation.md) | Warning|
|[UseConsistentIndentation](./UseConsistentIndentation.md) | Warning|
|[UseConsistentWhitespace](./UseConsistentWhitespace.md) | Warning|
1 change: 1 addition & 0 deletions RuleDocumentation/UseConsistentIndentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Indentation should be consistent throughout the source file.
Enable = $true
NoEmptyLineBefore = $false
}
}
```

### Parameters
Expand Down