ruby
Support `:api:` tag directive
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
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.
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'.
@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 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?
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".
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.
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:.
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.