Documentation coverage analysis

[enanox]

Hi, it would be completely awesome to include some kind of metrics or summary for documentation coverage, in a similar way as this.
I would do my best to create a pull request (but it would take me a while) with the idea if you find it useful, so please let me know!

[0815fox]

What would be completeness for you? Every class has a comment block? Every method? You could however write a plugin which adds this feature, then every-1 can chose to use it or not.

E.g. I avoid writing documentation if the name of a method is clean (Like getChildCount returns the total count of childs in this instance).

[enanox]

Yes, surely it would be an opt-in, and in no way as a mandatory check.
The rule of thumb you mention is certainly the way to go with coding as a whole, even libraries for other languages such as Foundation or UIKit for Obj-C have been following this approach and it really pays off.
However, in the context of very big applications or codebases that are spread and customized over various dev teams (think in a productization strategy), this is a necessity to avoid misuse, bad practices and such, since the former developers don't know by heart the whole codebase (and when time passes by, it's more and more difficult!) and we even could give a glimpse of how to use a class, widget, component, and so.

Hope this clearifies the intent, nonetheless, I agree with all you've said.

[0815fox]

Of course I am looking forward to seeing this. Would be nice, to switch it on for classes, interfaces, methods and properties in seperate. Maybe you also want to add a 'needsNoComment'-Tag, which works like a suppress warning in a linter?

[justmoon]

Perhaps this should be a tslint feature, not a typedoc feature?

[enanox]

@justmoon yes, they added here the completed-docs rule to enforce this behavior as a code style rule. Sorry for the delay on this, I'll close it. 🙏

[cjduncana]

Now that TSLint is deprecated and the completed-docs is not part of ESLint, will this project reconsider opening this issue?

[Gerrit0]

TypeDoc can do this today - apparently it slipped through the cracks and isn't documented in the website though. PR welcome to fix, or I'll be doing a review of all the options when revisiting the docs for 0.23, so should get it there.

1. Turn on "validation.notDocumented" either with "validation": { "notDocumented": true } or --validation.notDocumented
2. Configure "requiredToBeDocumented" with the types you want documented ("Class", "Interface", etc.). Throw a bad value in there and TypeDoc will print out all the options when trying to run. Note: Some values are effectively aliases of others. Accessor is equivalent to providing GetSignature and SetSignature.

[cjduncana]

Excellent! 🙌🏻 Let me play around with it to gain a better understanding of how it works before I update the documentation.