Doctor

Ensure that your documentation is healthy with Doctor! This library contains a mix task that you can run against your project to generate a documentation coverage report. Items which are reported on include: the presence of module docs, which functions do/don't have docs, which functions do/don't have typespecs, and if your struct modules provide typespecs. You can generate a .doctor.exs config file to specify what thresholds are acceptable for your project. If documentation coverage drops below your specified thresholds, the mix doctor task will return a non zero exit status.

The primary motivation with this tool is to have something simple which can be hooked up into CI to ensure that project documentation standards are respected and upheld. This is particular useful in a team environment when you want to maintain a minimum threshold for documentation coverage.

Installation

Adding :doctor to your list of dependencies in mix.exs:

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

Documentation can be found at https://hexdocs.pm/doctor.

Comparison with other tools

There are a few tools in the Elixir ecosystem that overlap slightly in functionality with Doctor. It is useful for you to know how Doctor differs from these tools and some use cases that Doctor serves.

Credo

Credo is a phenomenal library that can be used to perform a wide range of static analysis checks against your codebase. It can check for lingering IO.inspect() statements, it can check for unsafe atom conversions, and it can also check that the cyclomatic complexity of control statements is within a particular range to name a few.

The one area where Doctor and Credo do overlap is that with either tool you have the capability to enforce that @moduledoc attributes are present in modules. Given that this is the only overlap between the two tools, I generally use both in my projects and perform both validations during CI/CD.

Inch

Inch is another great tool written by René Föhring that is specifically catered to analyzing a project's documentation (very much like Doctor). Inch will scan your project's source files and check for the presence of function documentation and report back to you what grade it thinks your project has earned.

Inch does not appear to support checking for function typespecs, returning non-zero status codes when validation fails, tuning thresholds via a configuration file, or checking for struct module typespecs. On the other hand, these were things that were important to me personally and so I wrote Doctor to fill that void. In a team context, I find Doctor to be invaluable in ensuring that a project maintains a certain level of documentation by failing CI/CD if certain thresholds have not been met.

If I have misrepresented any of the aforementioned libraries...feel free to open up an issue :).

Usage

Doctor comes with 2 mix tasks. One to run the documentation coverage report, and another to generate a .doctor.exs config file.

To run the doctor mix task and generate a report, run: mix doctor. To generate a .doctor.exs config file with defaults, run: mix doctor.gen.config. To get help documentation, run mix help doctor and mix help doctor.gen.config. The outputs of those help menus can be seen here:

Running mix help doctor yields:

                                   mix doctor

Doctor is a command line utility that can be used to ensure that your project
documentation remains healthy. For more in depth documentation on Doctor or to
file bug/feature requests, please check out https://github.com/akoutmos/doctor.

The mix doctor command supports the following CLI flags (all of these options
and more are also configurable from your .doctor.exs file). The following CLI
flags are supported:

    --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.

Running mix help doctor.gen.config yields:

                             mix doctor.gen.config

Doctor is a command line utility that can be used to ensure that your project
documentation remains healthy. For more in depth documentation on Doctor or to
file bug/feature requests, please check out https://github.com/akoutmos/doctor.

The mix doctor.gen.config command can be used to create a .doctor.exs file with
the default Doctor settings. The default file contents are:

    %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
    }

Configuration

Below is a sample .doctor.exs file with some sample values for the various fields:

%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
}

For the reporter field, the following reporters included with Doctor:

Doctor.Reporters.Full
Doctor.Reporters.Short
Doctor.Reporters.Summary

Sample reports

Report created for Doctor itself:

$ mix doctor
Doctor file found. Loading configuration.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Doc Cov  Spec Cov  Module                                   File
Functions  No Docs  No Specs  Module Doc  Struct Spec
100%     0%        Doctor.CLI                               lib/cli/cli.ex                                            2
0        2         Yes         N/A
100%     0%        Doctor.Config                            lib/config.ex                                             3
0        3         Yes         Yes
100%     0%        Doctor.Docs                              lib/docs.ex                                               1
0        1         Yes         Yes
N/A      N/A       Doctor                                   lib/doctor.ex                                             0
0        0         Yes         N/A
100%     100%      Mix.Tasks.Doctor                         lib/mix/tasks/doctor.ex                                   1
0        0         Yes         N/A
100%     0%        Mix.Tasks.Doctor.Gen.Config              lib/mix/tasks/doctor.gen.config.ex                        1
0        1         Yes         N/A
100%     0%        Doctor.ModuleInformation                 lib/module_information.ex                                 4
0        4         Yes         Yes
100%     0%        Doctor.ModuleReport                      lib/module_report.ex                                      1
0        1         Yes         Yes
100%     0%        Doctor.ReportUtils                       lib/report_utils.ex                                       9
0        9         Yes         N/A
N/A      N/A       Doctor.Reporter                          lib/reporter.ex                                           0
0        0         Yes         N/A
100%     0%        Doctor.Reporters.Full                    lib/reporters/full.ex                                     1
0        1         Yes         N/A
100%     0%        Doctor.Reporters.OutputUtils             lib/reporters/output_utils.ex                             1
0        1         Yes         N/A
100%     0%        Doctor.Reporters.Short                   lib/reporters/short.ex                                    1
0        1         Yes         N/A
100%     0%        Doctor.Reporters.Summary                 lib/reporters/summary.ex                                  1
0        1         Yes         N/A
100%     0%        Doctor.Specs                             lib/specs.ex                                              1
0        1         Yes         Yes
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Summary:

Passed Modules: 15
Failed Modules: 0
Total Doc Coverage: 100.0%
Total Spec Coverage: 3.7%

Doctor validation has passed!

Report created for Phoenix: