:nodoc: comments & the like show as 'self.with_docs'

[KyFaSt]

ActiveRecord::Reflection::AggregateReflection#mapping shows in the user's inbox as docs to read about but the comment read :nodoc:

I propose blacklisting specific text from comments & then using the black list as a filter for comments to be suggested for reading & writing. This could look something like:

class DocComment < ActiveRecord::Base
...
validates :comment, exclusion: BLACKLIST
....
BLACKLIST = [ ":nodoc:", "documentation needed", "needs documentation", "todo"]

[schneems]

I would stick only with "official" undocumented tags. It would be really hard to blacklist unoficcial tags like "todo" or "needs documentation". If someone has a comment that says that, they should likely also add an "official" tag like :nodoc:.

I was hoping to get some support from YARD for pulling this meta data out, however it looks like it doesn't actually support :nodoc: https://rubydoc.tenderapp.com/kb/getting-started-with-rubydocinfo/where-is-my-nodoc

We have a skip_write flag on docs. We could have a skip_read as well and flag it under certain conditions, however I need to do some more meditation on the behavior we want here.

[KyFaSt]

That's not unreasonable to stick to only the official undocumented tags.

I understand that you want to think about this but I think it could be valuable to redirect :nodoc: comments to the the "to write" docs section. Seeing :nodoc: does make me think that the commenter believed documentation is needed, otherwise why comment at all?

Should you decide this is worthwhile, let me know & I can open a PR if you like

[schneems]

Unfortunately :nodoc: is VERY ambiguous. In Rails it means that the method is private and it should not be used as it may change. I don't think a ton of people know this though. In other projects it may mean something totally different. The least presumptious thing to do would be to add a skip_read flag if the comment when stripped of whitespace equals exactly :nodoc:. We can then query for only methods that don't have the skip_read boolean flagged before sending out. This will have the side effect of also not showing it to people who want to write docs as there is technically a comment there.

I would love a PR for this. Take a look at how I did skip_write support. You'll have to add the flag in the db, then set it in the parser, and check the flag before emails get generated. It shouldn't be toooo crazy, ping me if you have any questions. I'll be out on vacation soon, but i'll try to answer them as soon as I can.

[dgmstuart]

Hmm. Looks like #10 was merged, but I've just got an email with a :nodoc: in it: http://www.docsdoctor.org/doc_methods/80597

(Also http://www.docsdoctor.org/doc_methods/54814, which has :nodoc but I guess that's actually not a valid annotation?)