DOCSEARCHbyAlgolia
Submit Docs

DefaultDocumentation

repository·master·Indexed 41 days ago

https://github.com/doraku/defaultdocumentation

A tool that generates Markdown documentation from .NET assemblies and their corresponding XML documentation comments produced by Visual Studio. It can be integrated as an MSBuild task via a NuGet package or used as a standalone dotnet tool (DefaultDocumentation.Console). Supports features such as <inheritdoc/>, custom plugins via DefaultDocumentation.Api, and configurable output for namespaces, types, and members.

Tokens
88K
Snippets
498
Records
659
Agent score
48%

What's inside DefaultDocumentation

  2. Represent assembly and namespace documentation

    master

    The DefaultDocumentation.Models namespace contains specialized classes for different levels of the documentation hierarchy:

    • AssemblyDocItem: Represents an entire assembly's documentation.
    • NamespaceDocItem: Represents a specific namespace within an assembly.
    • EntityDocItem: Represents documentation for an IEntity (from ICSharpCode.Decompiler.TypeSystem). It exposes the underlying Entity property.

  3. Represent various type kinds with DocItem classes

    master

    The DefaultDocumentation.Models.Types namespace provides specific classes to represent different ITypeDefinition kinds. Most of these are initialized using a constructor that takes a DocItem, an ITypeDefinition, and an XElement.

    Supported type kinds include:

    • ClassDocItem: Represents TypeKind.Class.
    • DelegateDocItem: Represents TypeKind.Delegate. It includes properties for InvokeMethod (IMethod) and Parameters (ParameterDocItem).
    • EnumDocItem: Represents TypeKind.Enum.
    • InterfaceDocItem: Represents TypeKind.Interface.
    • StructDocItem: Represents TypeKind.Struct.
    • TypeDocItem: A general representation for ITypeDefinition documentation, providing access to the Type (ITypeDefinition) and TypeParameters (TypeParameterDocItem).

  4. Access parameters via IParameterizedDocItem and ITypeParameterizedDocItem

    master

    Interfaces are provided to easily access parameter-related documentation for items that support them:

    • IParameterizedDocItem: Exposes a Parameters property of type ParameterDocItem.
    • ITypeParameterizedDocItem: Exposes a TypeParameters property of type TypeParameterDocItem.

  5. Implement custom file name generation with IFileNameFactory

    master

    The DefaultDocumentation.Markdown.FileNameFactories namespace provides several implementations of IFileNameFactory to control how documentation files are named and organized. You can choose or implement a factory based on your preferred file structure:

    • BaseMarkdownFileNameFactory: Generates files with a .md extension and replaces invalid characters based on the Markdown.InvalidCharReplacement setting. It includes a Clean(IGeneralContext) method to remove previously generated files from the OutputDirectory.
    • DirectoryNameFactory: Uses the DocItem.Name to create a directory hierarchy.
    • FullNameFactory: Uses the DocItem.FullName as the file name.
    • Md5Factory: Uses an MD5 hash of the DocItem.FullName as the file name.
    • NameAndMd5MixFactory: Combines the DocItem.Name and an MD5 hash of the DocItem.FullName.
    • NameFactory: Uses the DocItem.Name as the file name.

  6. Use a custom IFileNameFactory

    master

    To change how documentation files and folders are named and organized, implement the IFileNameFactory interface. Once implemented, you must explicitly select your factory using the following methods:

    • MSBuild task: Set the <DefaultDocumentationFileNameFactory> property.
    • Dotnet tool: Use the --FileNameFactory argument.

  8. Use `<inheritdoc/>` for documentation reuse

    master

    The inheritdoc element is supported to reuse existing documentation from base classes or interfaces.

    Note: This performs a full import of the inherited documentation; any additional XML documentation provided on the inheriting member will be ignored.

  9. Use DirectoryNameFactory for hierarchical documentation

    master

    The DirectoryNameFactory is an implementation of IFileNameFactory that organizes documentation into a directory hierarchy. It uses the Name property of a DocItem to determine the file name and its position within the directory structure.

    This factory is used at the configuration level to define how documentation files are named and where they are placed relative to each other in the output directory.

    public sealed class DirectoryNameFactory : DefaultDocumentation.Api.IFileNameFactory

  10. Extend DefaultDocumentation with Plugins

    master

    DefaultDocumentation is extensible via plugins. You can implement interfaces provided by the DefaultDocumentation.Api NuGet package to add custom features to the generation process.

    Usage: Register your plugin implementation using the Plugins setting in your configuration.

  11. Use the DefaultSection class for standard documentation grouping

    master

    The DefaultSection class is a composite implementation of ISection. It is used to group a predefined sequence of documentation sections into a single logical unit. When used, it renders the following sections in this specific order:

    1. TitleSection
    2. SummarySection
    3. DefinitionSection
    4. ConstructorOverloadsSection
    5. MethodOverloadsSection
    6. TypeParametersSection
    7. ParametersSection
    8. EnumFieldsSection
    9. InheritanceSection
    10. DerivedSection
    11. ImplementSection
    12. EventTypeSection
    13. FieldValueSection
    14. ValueSection
    15. ReturnsSection
    16. ExceptionSection
    17. ExampleSection
    18. RemarksSection
    19. SeeAlsoSection
    20. NamespacesSection
    21. ClassesSection
    22. StructsSection
    23. InterfacesSection
    24. EnumsSection
    25. DelegatesSection
    26. ConstructorsSection
    27. FieldsSection
    28. PropertiesSection
    29. MethodsSection
    30. EventsSection
    31. OperatorsSection
    32. ExplicitInterfaceImplementationsSection