AnalyzeCSharp Wyam.CodeAnalysis

Performs static code analysis on the input documents, outputting a new document for each symbol.
This module acts as the basis for code analysis scenarios such as generating source code documentation. All input documents are assumed to contain C# source in their content and are used to create a Roslyn compilation. All symbols (namespaces, types, members, etc.) in the compilation are then recursively processed and output from this module as documents, one per symbol. The output documents have empty content and all information about the symbol is contained in the metadata. This lets you pass the output documents for each symbol on to a template engine like Razor and generate pages for each symbol by having the template use the document metadata.

Package

This module exists in the Wyam.CodeAnalysis package which is not part of the core distribution. Add the following preprocessor directive to your configuration file to use it:
#n Wyam.CodeAnalysis
Alternatively, you can add all modules at once with the following preprocessor directive:
#n Wyam.All

Usage

  • AnalyzeCSharp()

Fluent Methods

Chain these methods together after the constructor to modify behavior.

  • WhereNamespaces(bool includeGlobal, params string[] namespaces)

    Limits symbols in the initial result set to those in the specified namespaces.

    • includeGlobal

      If set to true, symbols in the unnamed global namespace are included.

    • namespaces

      The namespaces to include symbols from (if namespaces is null, symbols from all namespaces are included).

  • WhereNamespaces(Func<string, bool> predicate)

    Limits symbols in the initial result set to those in the namespaces that satisfy the specified predicate.

    • predicate

      A predicate that returns true if symbols in the namespace should be included.

  • WherePublic(bool includeProtected = true)

    Limits symbols in the initial result set to those that are public (and optionally protected)

    • includeProtected

      If set to true, protected symbols are also included.

  • WhereSymbol(Func<ISymbol, bool> predicate)

    Controls which symbols are processed as part of the initial result set.

    • predicate

      A predicate that returns true if the symbol should be included in the initial result set.

  • WithAssemblies(IEnumerable<string> assemblies)

    Analyzes the specified assemblies.

    • assemblies

      Globbing patterns indicating the assemblies to analyze.

  • WithAssemblies(string assemblies)

    Analyzes the specified assemblies.

    • assemblies

      A globbing pattern indicating the assemblies to analyze.

  • WithAssemblySymbols(bool assemblySymbols = true)

    Controls whether assembly symbol documents are output.

    • assemblySymbols

      true to output assembly symbol documents.

  • WithCssClasses(string tagName, string cssClasses)

    While converting XML documentation to HTML, any tags with the specified name will get the specified CSS class(s). This is helpful to style your XML documentation comment rendering to support the stylesheet of your site.

    • tagName

      Name of the tag.

    • cssClasses

      The CSS classes to set for the specified tag name. Separate multiple CSS classes with a space (just like you would in HTML).

  • WithDocsForImplicitSymbols(bool docsForImplicitSymbols = true)

    By default, XML documentation comments are not parsed and rendered for documents that are not part of the initial result set. This can control that behavior and be used to generate documentation metadata for all documents, regardless if they were part of the initial result set.

    • docsForImplicitSymbols

      If set to true, documentation metadata is generated for XML comments on all symbols.

  • WithImplicitInheritDoc(bool implicitInheritDoc = true)

    This will assume inheritdoc if a symbol has no other code comments.

    • implicitInheritDoc

      If set to true, the symbol will inherit documentation comments if no other comments are provided.

  • WithInputDocuments(bool inputDocuments = true)

    Controls whether the content of input documents is treated as code and used in the analysis (the default is true).

    • inputDocuments

      true to analyze the content of input documents.

  • WithNamedTypes(Func<INamedTypeSymbol, bool> predicate = null)

    Restricts the initial result set to named type symbols (I.e., classes, interfaces, etc.). Also allows supplying an additional predicate on the named type.

    • predicate

      A predicate that returns true if the symbol should be included in the initial result set.

  • WithProjects(IEnumerable<string> projects)

    Analyzes the specified projects.

    • projects

      Globbing patterns indicating the projects to analyze.

  • WithProjects(string projects)

    Analyzes the specified projects.

    • projects

      A globbing pattern indicating the projects to analyze.

  • WithSolutions(IEnumerable<string> solutions)

    Analyzes the specified solutions.

    • solutions

      Globbing patterns indicating the solutions to analyze.

  • WithSolutions(string solutions)

    Analyzes the specified solutions.

    • solutions

      A globbing pattern indicating the solutions to analyze.

  • WithWritePath(Func<IMetadata, FilePath> writePath)

    This changes the default behavior for the generated WritePath metadata value, which is to place files in a path with the same name as their containing namespace. Namespace documents will be named "index.html" while other type documents will get a name equal to their SymbolId. Member documents will get the same name as their containing type plus an anchor to their SymbolId. Note that the default scheme makes the assumption that members will not have their own files, if that's not the case a new WritePath function will have to be supplied using this method.

    • writePath

      A function that takes the metadata for a given symbol and returns a FilePath to use for the WritePath metadata value.

  • WithWritePathPrefix(DirectoryPath prefix)

    This lets you add a prefix to the default WritePath behavior (such as nesting symbol documents inside a folder like "api/"). Whatever you supply will be combined with the WritePath. This method has no effect if you've supplied a custom WritePath behavior.

    • prefix

      The prefix to use for each generated WritePath.

Output Metadata

The metadata values listed below apply to individual documents and are created and set by the module as indicated in their descriptions.

  • CodeAnalysisKeys.Accessibility: System.String

    This is available for type, method, field, event, and property symbols and contains the declared accessibility of the symbol.

  • CodeAnalysisKeys.AllInterfaces: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all implemented interfaces. The collection is empty if the type doesn't implement any interfaces.

  • CodeAnalysisKeys.AttributeData: Microsoft.CodeAnalysis.AttributeData

    This is available for attribute symbols and contains the Roslyn Microsoft.CodeAnalysis.AttributeData instance for the attribute.

  • CodeAnalysisKeys.Attributes: IReadOnlyList<IDocument>

    This is available for type, method, field, event, property, parameter, and type parameter symbols and contains the type symbol documents for attributes applied to the symbol.

  • CodeAnalysisKeys.BaseTypes: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all base types (inner-most first).

  • CodeAnalysisKeys.CommentId: System.String

    A unique ID that identifies the symbol for documentation purposes.

  • CodeAnalysisKeys.CommentXml: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains the full unprocessed XML documentation comments content for this symbol. In addition, special metadata keys may be added for custom comment elements with the name [ElementName]Comments. These special metadata keys contain a Wyam.CodeAnalysis.OtherComment instance with the rendered HTML content (and any attributes) of the custom XML documentation comments with the given [ElementName].

  • CodeAnalysisKeys.ConstantValue: System.Object

    This is available for field symbols and contains the constant value (if one exists).

  • CodeAnalysisKeys.Constructors: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all constructors of the type. The collection is empty if the type doesn't have any explicit constructors.

  • CodeAnalysisKeys.ContainingAssembly: Wyam.Common.Documents.IDocument

    The document that represents the containing assembly (or null if this symbol is not from an assembly).

  • CodeAnalysisKeys.ContainingNamespace: Wyam.Common.Documents.IDocument

    The document that represents the containing namespace (or null if this symbol is not nested).

  • CodeAnalysisKeys.ContainingType: Wyam.Common.Documents.IDocument

    This is available for type, method, field, event, property, and parameter symbols and contains a document representing the containing type(ornull if no containing type).

  • CodeAnalysisKeys.DeclaringType: Wyam.Common.Documents.IDocument

    This is available for type parameter symbols and contains a document that represents the declaring type of the type parameter.

  • CodeAnalysisKeys.DerivedTypes: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all types derived from the type. The collection is empty if the type doesn't have any derived types.

  • CodeAnalysisKeys.DisplayName: System.String

    A display name for the symbol. For namespaces, this is the same as Wyam.CodeAnalysis.CodeAnalysisKeys.QualifiedName. For types, this is the same as Wyam.CodeAnalysis.CodeAnalysisKeys.FullName.

  • CodeAnalysisKeys.Example: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains the rendered HTML content from allexample XML documentation comments for this symbol.

  • CodeAnalysisKeys.Exceptions: System.Collections.Generic.IReadOnlyList`1

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains a collection of allexception XML documentation comments for this symbol with their name, link, and/or rendered HTML content.

  • CodeAnalysisKeys.ExtensionMethods: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all extension members applicable to the type.

  • CodeAnalysisKeys.FullName: System.String

    The full name of the symbol. For namespaces, this is the name of the namespace. For types, this includes all generic type parameters.

  • CodeAnalysisKeys.HasConstantValue: System.Boolean

    This is available for field symbols and indicates whether a constant value is available for the field.

  • CodeAnalysisKeys.ImplementingTypes: IReadOnlyList<IDocument>

    This is available for interface symbols and contains a collection of the documents that represent all types that implement the interface. The collection is empty if no other types implement the interface.

  • CodeAnalysisKeys.IsAbstract: System.Boolean

    Indicates if the symbol is abstract.

  • CodeAnalysisKeys.IsOverride: System.Boolean

    Indicates if the symbol is an override.

  • CodeAnalysisKeys.IsResult: System.Boolean

    By default only certain symbols are processed as part of the initial result set(such as those that match the specified predicate). If this value is true, then this symbol was part of the initial result set. If it is false, the symbol was lazily processed later while fetching related symbols and may not contain the full set of metadata.

  • CodeAnalysisKeys.IsStatic: System.Boolean

    Indicates if the symbol is static.

  • CodeAnalysisKeys.IsVirtual: System.Boolean

    Indicates if the symbol is virtual.

  • CodeAnalysisKeys.Kind: System.String

    This is the general kind of symbol. For example, the for a namespace this is "Namespace" and for a type this is "NamedType".

  • CodeAnalysisKeys.MemberNamespaces: IReadOnlyList<IDocument>

    This is available for namespace symbols and contains a collection of the documents that represent all member namespaces. The collection is empty if there are no member namespaces.

  • CodeAnalysisKeys.Members: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all members of the type, including inherited ones. The collection is empty if the type doesn't have any members.

  • CodeAnalysisKeys.MemberTypes: IReadOnlyList<IDocument>

    This is available for namespace and type symbols and contains a collection of the documents that represent all member types. It only contains direct children (as opposed to all nested types).

  • CodeAnalysisKeys.Name: System.String

    The name of the symbol, or an empty string if the symbol has no name (like the global namespace).

  • CodeAnalysisKeys.Operators: IReadOnlyList<IDocument>

    This is available for type symbols and contains a collection of the documents that represent all operators of the type, including inherited ones. The collection is empty if the type doesn't have any operators.

  • CodeAnalysisKeys.OverriddenMethod: Wyam.Common.Documents.IDocument

    This is available for method symbols and contains a document that represents the method being overridden (or null if no method is overriden by this one).

  • CodeAnalysisKeys.Parameters: IReadOnlyList<IDocument>

    This is available for method and property (I.e., indexer) symbols and contains a collection of the documents that represent the parameters of the method or property.

  • CodeAnalysisKeys.Params: System.Collections.Generic.IReadOnlyList`1

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains a collection of allparam XML documentation comments for this symbol with their name, link, and/or rendered HTML content.

  • CodeAnalysisKeys.Permissions: System.Collections.Generic.IReadOnlyList`1

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains a collection of allpermission XML documentation comments for this symbol with their name, link, and/or rendered HTML content.

  • CodeAnalysisKeys.QualifiedName: System.String

    The qualified name of the symbol which includes all containing namespaces.

  • Keys.RelativeFileDir: Wyam.Common.IO.DirectoryPath

    The same as the directory of Wyam.Common.Meta.Keys.WritePath. This metadata key is available for compatibility with other modules.

  • Keys.RelativeFilePath: Wyam.Common.IO.FilePath

    The same as Wyam.Common.Meta.Keys.WritePath. This metadata key is available for compatibility with other modules.

  • Keys.RelativeFilePathBase: Wyam.Common.IO.FilePath

    The same as Wyam.Common.Meta.Keys.WritePath without the file extension. This metadata key is available for compatibility with other modules.

  • CodeAnalysisKeys.Remarks: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains the rendered HTML content from allremarks XML documentation comments for this symbol.

  • CodeAnalysisKeys.Returns: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains the rendered HTML content from allreturns XML documentation comments for this symbol.

  • CodeAnalysisKeys.ReturnType: Wyam.Common.Documents.IDocument

    This is available for method symbols and contains a document that represents the return type of the method (or null if the method returns void).

  • CodeAnalysisKeys.SeeAlso: IReadOnlyList<string>

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains a collection of allseealso XML documentation comments for this symbol with their rendered HTML link (or just name if no link could be generated).

  • CodeAnalysisKeys.SpecificKind: System.String

    The more specific kind of the symbol ("Class", "Struct", etc.) This is the same as Kind if there is no more specific kind.

  • CodeAnalysisKeys.Summary: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains the rendered HTML content from allsummary XML documentation comments for this symbol.

  • CodeAnalysisKeys.Symbol: ISymbol (or System.Collections.Generic.IEnumerable`1 if a namespace)

    The Roslyn ISymbol from which this document is derived. If the document represents a namespace, this metadata might contain more than one symbol since the namespaces documents consolidate same-named namespaces across input code and assemblies.

  • CodeAnalysisKeys.SymbolId: System.String

    A unique ID that identifies the symbol (can be used for generating folder paths, for example).

  • CodeAnalysisKeys.Syntax: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains a generated syntax example for the symbol.

  • CodeAnalysisKeys.Type: Wyam.Common.Documents.IDocument

    This is available for field, event, property, and parameter symbols and contains the document that represents the type of the symbol.

  • CodeAnalysisKeys.TypeParameters: IReadOnlyList<IDocument>

    This is available for type and method symbols and contains a collection of the documents that represent all generic type parameters of the type or method. The collection is empty if the type or method doesn't have any generic type parameters.

  • CodeAnalysisKeys.TypeParams: System.Collections.Generic.IReadOnlyList`1

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains a collection of alltypeparam XML documentation comments for this symbol with their name, link, and/or rendered HTML content.

  • CodeAnalysisKeys.Value: System.String

    This is available for documents in the initial result set (Wyam.CodeAnalysis.CodeAnalysisKeys.IsResult is true) and contains the rendered HTML content from allvalue XML documentation comments for this symbol.

  • Keys.WritePath: Wyam.Common.IO.FilePath

    A write path is generated for each symbol during code analysis and serves several purposes.First, it's used to automatically create hyperlinks for references in XML documentation comments.It can also be used for generating inbound links from other modules or pipelines to a given symbol. Because the WriteFiles module will check for any WritePath metadata values when outputting documents, this metadata also makes writing symbol documents to disk easier (presumably after they've been sent through a templating module).

GitHub