Add semantic functions to the XPath queries of MA0240
What
This PR adds thirteen functions to the XPath queries of MA0240. Each one works on the node it is evaluated on, whether that node is a syntax node, an operation, or a symbol:
| Function | Returns |
|---|---|
implements(type[, format]) | true when the type of the node implements the interface. The type itself is excluded. |
inherits-from(type[, format]) | true when type is one of the base classes of the node's type |
is-assignable-to(type[, format]) | true when the node's type is type, derives from it, or implements it |
has-attribute(type[, format]) | true when the symbol has an attribute whose class is type or derives from it |
attributes() / attributes(nodes) | AttributeData elements with ConstructorArgument, NamedArgument and Item children |
containing-assembly() / containing-assembly(name) | The assembly name, or a case-insensitive test of it |
is-from-current-assembly() | true when the symbol is declared in the analyzed project |
containing-namespace() / containing-namespace(name) | The namespace of the symbol, or an exact test of it |
overrides(member) | true when the symbol overrides member, directly or transitively |
implements-member(member) | true when the symbol implements that interface member, implicitly or explicitly |
is-externally-visible() | true when the symbol and all its containing types are public, protected or protected internal |
is-captured() | true for a local or a parameter used by a lambda or a local function |
file-path() | The path of the analyzed file, with / separators. It does not need the semantic model |
The type argument accepts three formats: MetadataName, DocumentationDeclarationId, and DocumentationReferenceId. The format is detected from the name: a T: prefix means a declaration ID, and a { means a reference ID. An optional second argument overrides the detection. Only reference IDs match specific type arguments. Variance is not considered.
The member argument of overrides and implements-member is either a documentation ID (M:System.Object.Equals(System.Object), which selects one overload) or a qualified name (System.Object.Equals, which selects every overload). The format is detected from the M: prefix.
Why
Until now, a query could only match a type by its exact name. It could not test the inheritance chain, the interfaces, or the attributes of a type. Also, the symbol() function only reaches the symbols declared in the file, so a query could not tell where a referenced symbol comes from.
Notes for reviewers
- The functions take the semantic model from the XSLT context, not from the navigator. As a result, they also work on the nodes that
syntax()returns in operation and symbol queries. - A plain syntax query that uses one of these functions is promoted to
SemanticSyntax, so it gets the semantic model. - The XPath engine does not check
Minargs/Maxargsfor context functions.ResolveFunctionnow checks the argument count itself, so MA0241 reports a call with the wrong number of arguments. This also applies tosyntax()andsymbol(), which previously matched nothing when called with the wrong count. - MA0241 reports a type-name format given as a string literal when the format is not one of the three valid names.
attributes(nodes)makes it possible to report the attributes themselves. They are reported on the attribute syntax asAttributeData. Attributes that come from metadata can be tested, but they are not reported.file-path()lets an entry apply to some files only. An.editorconfigseverity applies to every entry at once. Plain syntax queries now get a context that holds only the syntax tree, sofile-path()works in them without requesting the semantic model.is-captured()usesSemanticModel.AnalyzeDataFlowon the body that declares the symbol. The result is cached per body. The parameters of a primary constructor are not considered.docs/Rules/MA0240.mdhas a new "Semantic functions" section, anddocs/Rules/MA0241.mdis updated.
Testing
- 58 new test cases in
DoNotUseBannedSyntaxAnalyzerTests. All 270 tests in that class pass on roslyn 4.8, 4.14, 5.0, 5.6 and 5.9. - The full roslyn5.9 suite passes (5,070 tests).
dotnet run --project src/DocumentationGeneratorexits with code 0.