From c5f7a2857abff2b60afe58f9e63f3a56d7a33a6a Mon Sep 17 00:00:00 2001 From: Loren Segal Date: Sat, 4 Nov 2017 13:13:45 -0700 Subject: [PATCH] Add note about when to use @!attribute and @!method Fixes #1126 Fixes #1128 --- lib/yard/tags/directives.rb | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/yard/tags/directives.rb b/lib/yard/tags/directives.rb index d505d1279..a76ea4006 100644 --- a/lib/yard/tags/directives.rb +++ b/lib/yard/tags/directives.rb @@ -338,6 +338,10 @@ def warn # # To define an attribute method, see {tag:!attribute} # + # @note This directive should only be used if there is no explicit + # declaration for the method in any source files (i.e., the method + # is declared dynamically via meta-programming). In all other cases, add + # documentation to the method definition itself. # @note For backwards compatibility support, you do not need to indent # the method's docstring text. If a +@!method+ directive is seen with # no indented block, the entire docstring is used as the new method's @@ -431,6 +435,10 @@ def create_object # # To define a regular method, see {tag:!method} # + # @note This directive should only be used if there is no explicit +attr_*+ + # declaration for the attribute in any source files (i.e., the attribute + # is declared dynamically via meta-programming). In all other cases, add + # documentation to the attribute declaration itself. # @note For backwards compatibility support, you do not need to indent # the attribute's docstring text. If an +@!attribute+ directive is seen with # no indented block, the entire docstring is used as the new attribute's