akoutmos / doctor

Ensure that your Elixir project documentation is healthy
MIT License
179 stars 15 forks source link

Do not report missing docs for exceptions #36

Closed pnezis closed 3 years ago

pnezis commented 3 years ago

In case of a defexception the convention is to not have a moduledoc, struct type spec can be ignored as well since the __struct__ is injected from the defexception macro.

akoutmos commented 3 years ago

Thanks for opening up this PR! I can get on board with the typespec skipping...but personally I usually add moduledocs for exceptions so codebase readers know when that exception can occur (sort of how it is done in Ecto https://github.com/elixir-ecto/ecto/blob/master/lib/ecto/exceptions.ex). Thoughts?

pnezis commented 3 years ago

@akoutmos I also add moduledocs to exceptions but in most projects (elixir itself included) this is not the case. I could add a config option for defining if the moduledoc in exceptions is required or not. What do you think?

akoutmos commented 3 years ago

That's a fair point with regards to the Elixir codebase itself. I'd be good with a config flag for moduledoc enforcement on exception modules. Think that get's use to a best of both worlds scenario :).

pnezis commented 3 years ago

@akoutmos I added an exception_moduledoc_required config option which defaults to true.

Also included in the PR:

Regarding the implementation of the extra option I considered several approaches:

I finally settled with adding a generic properties field in ModuleInformation which is copied to ModuleReport. The main reasoning for this is extensibility. In the future some extra corner cases may need to be handled, or some extra checks may need to be added, and a generic properties field would make any future enhancement of such kind easy. Thoughts?

akoutmos commented 3 years ago

Really like all the changes that you have put together @pnezis! I'll pull this down and play with it either today or tomorrow and if all looks good I'll merge it in. Thanks!

pnezis commented 3 years ago

Thanks for merging this @akoutmos

akoutmos commented 3 years ago

Thank you for the awesome contribution :). I'll cut a new release in the coming days.