Support `:api:` tag directive

[zzak]

Possible options:

• public
• private
• protected

Option 1:

• Provide support for tags
• Let plugin generators handle markup

Option 2:

• Provide support for tags
• Implement markup for darkfish

[fxn]

In principle, in Rails we only need a directive :private: akin to YARD's @private tag.

The problem that directive would address would be to be able to mark something as private for end-users, even if for implementation purposes within the library it has public Ruby visibility.

Nowadays we are nodoc'ing those cases, but a :private: flag would commuicate better the intention I believe.

From RDoc we would only need that :private: stuff is not generated. As a bonus point maybe a flag would enable generation, but Rails doesn't need that flag.

[fxn]

Let me add a cross-link with rails/rails#13989.

[drbrain]

How is this different from section/category support?

Note that RDoc has special handling if you only use 'Internal, Public, Deprecated'. I think the 'Internal' category is the same idea as 'private'.

[fxn]

@drbrain RDoc would not generate content for :private:. There is no API to generate for those methods. That would be useful for deprecated methods though, we are not leveraging that feature and looks interesting.

[drbrain]

Then :private: sounds the same as :nodoc: to me, am I right?

[fxn]

@drbrain exactly, only it would go at the beginning of the comment to be really obvious instead of where we place :nodoc: now. I imagine something like this:

# :private:
#
# Internal documentation.
def internal_method
  ...
end

Does that make sense?

[fxn]

Ah let me add that it would be the same in the sense that they do not generate docs. The difference in my view lies in the intention. I don't want to say "do not generate docs", I want to say "whoever is reading this, please note it is internal".

[fxn]

... the method, module, etc. is private, can't express that with #-- either.

[drbrain]

I understand and I think I like this concept.

Since "private" is an overloaded word, how about "internal"?

Sometimes I want to use ri or the html to read the internal documentation when I'm working on a bug fix or new feature, so I may add a flag to include the "private" or "internal" in the generated output for developers.

[fxn]

Sounds even better.

[zzak]

I agree that most use-cases simply want to mark something as internal documentation, without going through the :nodoc: hoops.

Currently when generating documentation you have the ability to include all things marked :nodoc: using the --all tag (or -a). This flag essentially sets RDoc::Options#visibility to :private:, which means include everything.

Since #276 was merged, this method is now public api, with a synonym of :all: for :private:.

When adding :internal:, it should be included in the Options#visibility configuration so that we can specify to include public -> internal -> all level documentation, in that order. ie: :internal: wouldn't include stuff marked as :nodoc:.

[zzak]

I talked to @rafaelfranca today about adding :plugin: as well, for handling private methods that (for example: can be overridden by a subclass).

Essentially this directive would be the opposite of :nodoc:, we could call it "doc" but I think :plugin: is more explicit in its intention.

Since RDoc ignores private methods by default, unless using the --all option, this directive would let RDoc know to include this method regardless of the option.