Package

#n Wyam.CodeAnalysis

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.

Settings

The settings listed below apply globally and can be set from the command line or from a configuration file. They are used to configure options and otherwise control module behavior.

• CodeAnalysisKeys.OutputBuildLog: System.Boolean

  Set this to true in the global settings to generate a binary build log when analyzing projects or solutions. The log will be output alongside the project file.

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: Microsoft.CodeAnalysis.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).