Some constructions, modifying the behavior, should be annotated in order to enrich the information of the AST

[LaurentDardenne]

[Void]

$T=[SystemsCollections.ArrayList]::New(); [void]$T.Add(1); $T.Add(2) > $null

Here [void] is not only a cast but modifies the emission of a data in the pipeline and avoids a side effect, so it is a behavior to be aware of.
See
"This type cannot be instantiated. It provides a means to discard a value explicitly using the cast operator"

Comma operator with Return

$T=[SystemsCollections.ArrayList]::New();Return ,$T ; $a = ,10	

For the 'Return' instruction, the comma operator avoids enumerating the collection (cf. Write-Output -NoEnumerate), in this case we want to retrieve the type of the collection and its content and not just the content of the collection, it is therefore a behavior to be aware of.

There is also this specific case (rare) :

$Collection=@(1,2,'Test',10.5,8); $method = [System.Linq.Enumerable].GetMethod('OfType'); $m = $method.MakeGenericMethod([int]);$m.Invoke($null, (,$Collection))

Because of the method signature :

$m.Invoke
#System.Object Invoke(System.Object obj, System.Object[] parameters)

Variable name with space

${name with space}='Content' ;$name='Content'

Switch parameter and a value

 Remove-Item $path -Confirm:$false -Force

[LaurentDardenne]

Filter

function Get-Square2 { $_ * $_ }; Filter Get-Square2 { $_ * $_ }

A function with a particular behavior.

[Jawz84]

@LaurentDardenne would you have a proposal for what explanations for these should look like?

Please note that function and filter both do not have an explanation in the code base yet.

[LaurentDardenne]

>>would you have a proposal for what explanations for these should look like?
I was thinking of a note associated with the statement definition.
For the following example:

[void]$T.Add(1) ; $T.Add(2) > $null

The objective is identical but the syntax is different, here it is more an intention that needs to be explained, it is a recognition of instruction patterns.

[Jawz84]

A good suggestion I think.
For the [void] type, that would be easy to do I think, as the only possible intent can be to suppress output, and only TypeConstraintAst is in play.
For the ... > $null situation, which is similar to $null = ... and ... | Out-Null, the intent is the same, but will be harder to catch to provide the correct explanation, because at least two Ast's together produce the intent. Out-Null already has a description that conveys this intent. That only leaves $null with an assignment and $null with a redirection. I think we can handle this at the variableExpressionAst -> if the variable name is 'null', check parent Ast's. If it is either assignment (left hand side) or redirection (right hand side), add text to the description to explain the intent of suppressing output.
Could be done.

[LaurentDardenne]

>>For the ... > $null situation, which is similar to $null = ... and ... | Out-Null, the intent is the same,
>> but will be harder to catch to provide the correct explanation,
Yes, this is similar to the analyzes of PSSA.

For Out-null the documentation is explicit and logically an Out-xxx cmdlet should be the last statement in a pipeline.