SourceDocs
Calculate Documentation Percentage
I know some documentation tools have the ability to return the percentage documented. I'd love something like this to include in my CI along with SourceDocs. I am more than willing to help as well and add this feature. Where would something like this be calculated and added?
Hi @leogdion, thank you for the suggestion. This is an interesting topic, and feature.
Where to calculate the percentage will depend on your definition:
- Should the total percentage be in the README file?
- Should it be on each document file?
- Maybe we would want a
sourcedocs percentagecommand that prints the total percentage without generating any other output?
In terms of calculation, SourceDocs loads all entities (classes, methods, etc) from code, whether they are documented or not. We could count the number of entities that have documentation and calculate the percentage. The best place to do that would probably be in MarkdownIndex.swift.
I was thinking something fairly simple:
- Maybe we would want a
sourcedocs percentagecommand that prints the total percentage without generating any other output?
In other words just output the value with the command output (not included in any markdown files). My intention is to include it as part of my pre-commit hook or CI to ensure my documentation is up to certain threshold similar to how I can use swift-test-codecov in my pre-commit hook to ensure my test code coverage is fulfilled.
Feel free to look at how I do this with MistKit and code coverage. I'm going to look at MarkdownIndex.swift and see what I can do there.
Thanks for the pointers!
Nice. That would be a great tool, for sure. It might require some good amount of refactoring, to separate the documentation extraction logic from the markdown generation (right now it's all tangled together 🙈).
If you want to look into it, I would recommend starting by adding a new command, then running the SourceKitten calls to parse the source files and load documentation. Feel free to duplicate any code, if you want to go this route, we can tidy it up later.
Hi @leogdion, just left you a comment on the PR. please try pulling the latest changes from the main branch (master branch is no longer used).
If you don't mind, and have the time, it would be nice to clean up the command, specially all the parameters (arguments) not being used or needed for this command. Instead, you can pass default values to the documentation generator.