Checking completeness of documentation using coverage

[Cedrick84]

Hi guys,

I have no idea if this is the correct section to ask this I have a couple of questions, feel free to close this if this is not appropriate to do so here.

I am very interested in the "coverage" part of the tool. I would like to check that all documentation is up to date and complete. Now when I create a test class with some methods and play around with the method signatures but keep the old documentation (this either doesn't have the correct parameters anymore or names have changed/new ones are added) the coverage still tells me that it's 100% as long as there is anything documented.

I would like to ask if there is a possibility to check that the documentation is present and all parameters are documented (and no "old" parameters are documented).

It would also be really nice if there would be an option to also include non public methods/classes in the coverage report, maybe with a separate flag?

Many thanks for all the effort that has been put into this project!

[Lukas-Stuehrk]

I would like to ask if there is a possibility to check that the documentation is present and all parameters are documented (and no "old" parameters are documented).

The current implementation of the coverage subcommand simply checks if any documentation is present. It does not check if the documentation is coherent with the code, e.g. if all parameters are documented or if there are parameters in the documentation which do not appear in code. @mattt is this a feature we might want to support in the future? Then we could open a new issue to track this.

It would also be really nice if there would be an option to also include non public methods/classes in the coverage report, maybe with a separate flag?

This feature was implemented recently, but there hasn't been a new release in which this is included yet. There's a new flag --minimum-access-level which makes this possible. If you want to use it today, you can compile swift-doc from source using the instructions in the README.

[mattt]

The current implementation of the coverage subcommand simply checks if any documentation is present. It does not check if the documentation is coherent with the code, e.g. if all parameters are documented or if there are parameters in the documentation which do not appear in code. @mattt is this a feature we might want to support in the future? Then we could open a new issue to track this.

I think this would be a great feature to support in the future. I just filed #246 to track this.

In the meantime, check out DrString, which might provide the kind of functionality you're looking for.