DOCSEARCHbyAlgolia
Submit Docs

Doctor Documentation Health Tool

repository·master·Indexed 41 days ago

https://github.com/akoutmos/doctor

A documentation health tool for Elixir projects that audits module documentation, function documentation, and typespec coverage. It provides a Mix task (`mix doctor`) to generate coverage reports and can be integrated into CI/CD pipelines to enforce documentation standards using the `--raise` flag. Configuration is managed via a `.doctor.exs` file using the `%Doctor.Config{}` struct, allowing users to set thresholds for doc and spec coverage and exclude specific modules or paths.

Tokens
4.8K
Snippets
18
Records
22
Agent score
52%

What's inside Doctor

  1. Understand the Doctor report format

    master

    The Doctor report provides a tabular view of your project's documentation and specification health.

    Column Definitions:

    • Doc Cov: Percentage of function documentation coverage.
    • Spec Cov: Percentage of specification coverage.
    • Module: The name of the Elixir module.
    • File: The file path where the module is defined.
    • Functions: Total number of functions in the module.
    • No Docs: Count of functions missing documentation.
    • No Specs: Count of functions missing specifications.
    • Module Doc: Indicates if the module itself is documented (YES/NO/N/A).
    • Struct Spec: Indicates if structs within the module have specifications (Yes/No).

    Summary Section: At the end of the report, Doctor provides a summary including:

    • Passed Modules: Count of modules meeting requirements.
    • Failed Modules: Count of modules failing requirements.
    • Total Doc Coverage: Aggregate documentation percentage.
    • Total Spec Coverage: Aggregate specification percentage.
    • Doctor validation has passed!: A final status message indicating if the overall validation was successful.

  2. Configure Doctor via .doctor.exs

    master
    You can customize documentation thresholds and behavior by creating a .doctor.exs configuration file. You can generate a template with default values using the mix doctor.gen.config task.
    mix doctor.gen.config

  3. Install Doctor via mix.exs

    master

    To use Doctor in your Elixir project, add it to your deps in mix.exs. It is recommended to use the only: :dev option since it is a development/CI tool.

    def deps do
  [
    {:doctor, "~> 0.23.0", only: :dev}
  ]
end

  4. ModuleExplain report output format

    master

    The ModuleExplain report produces a formatted table and a summary section in the Mix shell:

    1. Function Table: A table listing each user-defined function, its arity, and whether it passed or failed the @doc and @spec checks.
    2. Module Results Summary: A summary section showing:
      • Has Struct Spec: Whether the module meets struct type spec requirements.
      • Has Module Doc: Whether the module has required module-level documentation.
      • Doc Coverage: The percentage of functions covered by @doc.
      • Spec Coverage: The percentage of functions covered by @spec.

    If a check fails, the report explicitly mentions which configuration value caused the failure (e.g., --> Your config has a 'min_module_doc_coverage' value of 80.0).

  5. Filter modules and paths using ignore patterns

    master

    When running reports, you can exclude specific modules or file paths using the following patterns in your args object:

    Ignore Modules (args.ignore_modules)

    • Atoms: Exact match for the module name (e.g., MyModule).
    • Regex: Matches against the module name string with the Elixir. prefix stripped (e.g., ~r/Test/).

    Ignore Paths (args.ignore_paths)

    • Strings: Exact match for the relative file path.
    • Regex: Matches against the relative file path.

  6. Generate a default .doctor.exs configuration file

    master
    You can use the mix doctor.gen.config Mix task to automatically create a .doctor.exs configuration file in your project root. This file contains the default settings for Doctor's documentation health checks. If a configuration file already exists, the task will prompt you before overwriting it.
    mix doctor.gen.config

  7. Configure Doctor settings in .doctor.exs

    master

    Doctor is configured using a %Doctor.Config{} struct within a .doctor.exs file. Below are the available configuration keys and their default values:

    KeyDefaultDescription
    ignore_modules[]List of modules to exclude from checks.
    ignore_paths[]List of file paths to exclude from checks.
    min_module_doc_coverage40Minimum required documentation coverage percentage for individual modules.
    min_module_spec_coverage0Minimum required specification coverage percentage for individual modules.
    min_overall_doc_coverage50Minimum required documentation coverage percentage for the entire project.
    min_overall_moduledoc_coverage100Minimum required documentation coverage percentage for all modules combined.
    min_overall_spec_coverage0Minimum required specification coverage percentage for the entire project.
    exception_moduledoc_requiredtrueWhether documentation is strictly required for exception definitions.
    raisefalseIf true, Doctor will raise an error if documentation requirements are not met.
    reporterDoctor.Reporters.FullThe module used to report the results of the health check.
    struct_type_spec_requiredtrueWhether type specifications are required for structs.
    umbrellafalseSet to true if the project is an Elixir umbrella application.
    %Doctor.Config{
  ignore_modules: [],
  ignore_paths: [],
  min_module_doc_coverage: 40,
  min_module_spec_coverage: 0,
  min_overall_doc_coverage: 50,
  min_overall_moduledoc_coverage: 100,
  min_overall_spec_coverage: 0,
  exception_moduledoc_required: true,
  raise: false,
  reporter: Doctor.Reporters.Full,
  struct_type_spec_required: true,
  umbrella: false
}

  8. Reference: mix doctor CLI flags

    master

    The mix doctor command supports the following flags to control report output and validation behavior:

        --full       When generating a Doctor report of your project, use
                 the Doctor.Reporters.Full reporter.

    --short      When generating a Doctor report of your project, use
                 the Doctor.Reporters.Short reporter.

    --summary    When generating a Doctor report of your project, use
                 the Doctor.Reporters.Summary reporter.

    --raise      If any of your modules fails Doctor validation, then
                 raise an error and return a non-zero exit status.

    --failed     If set only the failed modules will be reported. Works with
                 --full and --short options.

    --umbrella   By default, in an umbrella project, each app will be
                 evaluated independently against the specified thresholds
                 in your .doctor.exs file. This flag changes that behavior
                 by aggregating the results of all your umbrella apps,
                 and then comparing those results to the configured
                 thresholds.

  10. Reference: Doctor.Config schema

    master

    The .doctor.exs file uses a %Doctor.Config{} struct. Below is the default configuration schema provided by mix doctor.gen.config:

    %Doctor.Config{
  ignore_modules: [],
  ignore_paths: [],
  min_module_doc_coverage: 40,
  min_module_spec_coverage: 0,
  min_overall_doc_coverage: 50,
  min_overall_moduledoc_coverage: 100,
  min_overall_spec_coverage: 0,
  exception_moduledoc_required: true,
  raise: false,
  reporter: Doctor.Reporters.Full,
  struct_type_spec_required: true,
  umbrella: false
}

  11. Run Doctor validation via Mix

    master

    To run the Doctor validation tool on your Elixir project, use the mix doctor command.

    Doctor analyzes your project's modules to report on:

    • Doc Coverage: The percentage of functions documented using @doc.
    • Spec Coverage: The percentage of functions covered by @spec definitions.
    • Module Documentation: Whether the module itself has documentation.
    • Struct Specifications: Whether structs have defined specifications.

    If a configuration file (Doctor file) is found in your project, Doctor will load those settings. If no configuration file is found, it will run using default settings.

    $ mix doctor

  12. Run documentation coverage reports with mix doctor

    master

    Use the mix doctor command to generate a report on your project's documentation health. It checks for module docs, function docs, function typespecs, and struct module typespecs.

    By default, it reports findings but does not fail the build. To ensure CI/CD pipelines fail when documentation standards are not met, use the --raise flag.

    mix doctor