I can not be sure if we should merge the change.

Currently, the codebase does not contain any Yard tags. And the author of Yard wrote that using "@private" tag is "not recommended":https://github.com/lsegal/yard/issues/34#issuecomment-75793. Also, the patch changes the output of rdoc.

Sho HASHIMOTO, do you think those are OK?
--------------------------------------------------------------------------------
> Currently, the codebase does not contain any Yard tags.

umm... Redmine is already using Yard tags like these. rdoc can't parse normaly. I think supporting both(rdoc and yard) is unhappy. We can't use all of on one side only tag like :nodoc:, @param, ...

* https://github.com/redmine/redmine/blob/3.4.5/lib/redmine/plugin.rb#L140
* https://github.com/redmine/redmine/blob/3.4.5/app/helpers/application_helper.rb#L43-L46

> "@private" tag is not recommended.

I knew. Please remove :nodoc: if yard is taken and @private isn't used. Maybe yard recommends writing all documents.
--------------------------------------------------------------------------------
Redmine is not using important rdoc tag like call-seq, include, ...
Maybe, using yard will have only few problems.

<pre>
$ egrep '#\s*:[a-zA-Z]+:' **/*.rb
lib/plugins/open_id_authentication/lib/open_id_authentication.rb: def using_open_id?(identifier = nil) #:doc:
lib/plugins/open_id_authentication/lib/open_id_authentication.rb: def authenticate_with_open_id(identifier = nil, options = {}, &block) #:doc:
lib/redmine/core_ext/string.rb:class String #:nodoc:
lib/redmine/core_ext/string/conversions.rb:module Redmine #:nodoc:
lib/redmine/core_ext/string/conversions.rb: module CoreExtensions #:nodoc:
lib/redmine/core_ext/string/conversions.rb: module String #:nodoc:
lib/redmine/core_ext/string/inflections.rb:module Redmine #:nodoc:
lib/redmine/core_ext/string/inflections.rb: module CoreExtensions #:nodoc:
lib/redmine/core_ext/string/inflections.rb: module String #:nodoc:
lib/redmine/helpers/gantt.rb: # :nodoc:
lib/redmine/menu_manager.rb: class MenuError < StandardError #:nodoc:
lib/redmine/plugin.rb:module Redmine #:nodoc:
lib/redmine/scm/adapters/abstract_adapter.rb: class AbstractAdapter #:nodoc:
lib/redmine/scm/adapters/command_failed.rb: class CommandFailed < StandardError #:nodoc:
lib/redmine/scm/adapters/cvs_adapter.rb: # :pserver:anonymous@foo.bar:/path => /path
lib/redmine/scm/adapters/cvs_adapter.rb: # :ext:cvsservername:/path => /path
lib/redmine/version.rb: module VERSION #:nodoc:
test/mocks/open_id_authentication_mock.rb: def authenticate_with_open_id(identity_url = params[:openid_url], options = {}) #:doc:
</pre>

And I want to add @since tag after this ticket. It will be useful for plugin developper.
--------------------------------------------------------------------------------
Sho HASHIMOTO wrote:
> umm... Redmine is already using Yard tags like these. rdoc can't parse normaly. I think supporting both(rdoc and yard) is unhappy. We can't use all of on one side only tag like :nodoc:, @param, ...
>
> * https://github.com/redmine/redmine/blob/3.4.5/lib/redmine/plugin.rb#L140
> * https://github.com/redmine/redmine/blob/3.4.5/app/helpers/application_helper.rb#L43-L46

I had overlooked that. Thank you for pointing it out.

As Sho HASHIMOTO wrote, it is obvious that the document of Redmine is supposed to be generated with Yard because Redmine has a rake task "rake yard" and uses some Yard tags.

--------------------------------------------------------------------------------
Setting target version to 4.1.0.
--------------------------------------------------------------------------------
Maybe we can also remove :doc: tag. Do you think it is OK?
http://www.redmine.org/projects/redmine/repository/entry/tags/3.4.5/lib/plugins/open_id_authentication/lib/open_id_authentication.rb#L112
--------------------------------------------------------------------------------
It is no problem for me! Thanks!
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
Committed. Thanks.
--------------------------------------------------------------------------------
Thanks!!
--------------------------------------------------------------------------------