Code Triage shouldn't email me requests for private method documentation

[keoghpe]

I've opened this issue to continue a discussion I started with @schneems on Twitter. I subscribed to Rails on Code Triage to receive documentation requests. Unfortunately, most of the requests I got we're for modules with :nodoc: at the top of them or for private methods. It would be great if I only received requests for methods that needed to be documented.

I'm more than happy to work on this when I have time. It would be great to contribute to such an excellent project.

I'm not sure if it will be possible to eliminate the issue entirely, but hopefully I can bring the false positive rate down a little. It seems like the code I'll need to update is /lib/docs_doctor/parsers/ruby/yard.rb. Are there tests for this? If so where are they located?

Any help on this would be much appreciated.

[rubyrider]

I agree. I received a documentation issue for a :nodoc: module. Either they are private method or mostly the module is for internal class. If we can make it improved we would get more important parts for documentation. I would also like to work in this part for sure.

[schneems]

We are already detecting if it is a :nodoc: and setting a skip_read on the method https://github.com/codetriage/codetriage/blob/b5aabbc2ac149359cb17843a0e634fbe692a693d/lib/docs_doctor/parsers/ruby/yard.rb#L43

I still think we could use documentation on :nodoc: methods, it just means that it's not a public interface (in rails).

That code is tested via integration tests. The test suite will clone repos and run the doc parser on them.

I'm not sure about how we could make this a more flexible thing. Maybe allow a negative regex? Like give me all issues unless they match /:nodoc:/ or something? Have it set-able on a per-project basis. IDK.

[etagwerker]

Today I subscribed to see documentation opportunities in rails and I ended up here:

https://github.com/rails/rails/blob/c2847716913d3fb72fd423009be1d4f124e4aa94/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb/#L35-L41 (the link from CodeTriage took me to the initialize method)

I still think we could use documentation on :nodoc: methods, it just means that it's not a public interface (in rails).

@schneems do you think a PR with documentation for a :nodoc-flagged method would be welcomed in rails?

I realize that my issue is related to the dashboard (and it might be a new issue) but here is an idea: Could CodeTriage prioritize non :nodoc: methods when showing methods to be documented?