`@!macro` cannot attach to DSL methods in `@!parse`

[UlyssesZh]

@!macro cannot attach to DSL methods in @!parse.

Steps to reproduce

Write these in lib/test.rb:

# A test class.
class Test

  # @!macro [attach] property
  #   @return [$2] the $1 property
  # @!parse property :title, String

  # @!parse property :view_count, Integer
end

Run yard doc --debug.

Actual Output

No methods are documented.

Expected Output

It should be equivalent to this:

# A test class.
class Test

  # @!macro [attach] property
  #   @return [$2] the $1 property
  property :title, String

  property :view_count, Integer
end

Environment details:

• OS: NixOS 24.05
• Ruby version (ruby -v): 3.3.4
• YARD version (yard -v): 0.9.37

I have read the Contributing Guide.

[aaronmallen]

This works:

# @!parse
#   # @!macro [attach] property
#   #   @return [$2] the $1 property
#   property :title, String

[lsegal]

Note

This is a batch message, apologies if this feels impersonal.

I am closing out a few stale issues and PRs in the YARD repo and this was flagged for automatic closure because the issue may have been fixed or is likely not planned due to the issue/PR age. If this is still an issue or you believe the issue/PR is still worth a discussion, please feel free to comment or reopen a new issue. Thanks and sorry for not getting around to this the first time!

[UlyssesZh]

I think this is still worth a discussion.

[lsegal]

@UlyssesZh see #1583 (comment)

This works:

# @!parse
#   # @!macro [attach] property
#   #   @return [$2] the $1 property
#   property :title, String

I think this is the expected way to achieve the result you're looking for. The issue is that the parse block in your example is disconnected from the macro, so there's lexically nothing to attach to. changing this would require semantic coupling in comment blocks between macro and other tags, something YARD has been moving away from with directives.

IMO this is how YARD should advise users achieve this if it was directly documented (it should probably be). In general, using comment within a @!parse block has been recommended before.

Sidenote: the reason this likely feels complex is because you're kind of overusing @!parse for something that the directive is really not meant for. The "attach" keyword in macro usage is meant to attach to a DSL statement. In your case, you're faking a DSL within the comment layer parsed only by YARD, and that's fundamentally not really a DSL, or at least not the DSL that macro is designed to support. What you should be doing is defining a regular property DSL in code and attaching there, if it REALLY is an attached macro.

[UlyssesZh]

I do think dynamically ganerating DSL methods is a common thing I like to do, but anyway, I think talking about DSL methods may be a bit off-track because macros (semantically) do not necessarily have to be used with DSL methods but are used for reducing repetitive documentation. Then what if I want to use one macro for both methods inside and outside @!parse?

[lsegal]

macros (semantically) do not necessarily have to be used with DSL methods

Sure, macros themselves aren't, but the attach feature is specifically designed for DSL methods. It really doesn't make sense to use attached macros for non-attachable code. Emulating this with @!parse is fine, but this seems like a Ruby anti-pattern. Where is this magical property even defined?

Then what if I want to use one macro for both methods inside and outside @!parse?

Once the macro is defined it works everywhere. This works:

# @!parse
#   # @!macro [attach] property
#   #   @return [$2] the $1 property
#   property :title, String

# @!parse property :view_count, Integer

# Even this
property :other, Boolean

But again, it kind of seems like you're skirting other YARD features like simply using @!attribute:

# @!attribute title
#   @return [String] documenting what kind of title you are exposing
# @!attribute view_count
#   @return [Integer] documenting how view count is calculated, hopefully!
class Test
end

Is it slightly more verbose? Sure, but presumably you're not just documenting each property as "the X property", so eventually even your property macro is going to fall apart once you actually, you know, need to provide documentation.

And if your goal is just to provide type information to your classes, you're actually better off just providing .rbs files to YARD as of v0.9.40 (though there admittedly is a little bit of a bug around attribute detection which will be fixed soon):

# sig/test.rbs
class Test
  # Docs here
  attr_reader title: String
  # Docs here
  attr_reader view_count: Integer
end

This is about all you're accomplishing with the macros above (technically the .rbs file is more powerful since you can actually customize per declaration docstrings).

tldr: yes, attach is specifically intended for DSL methods, not synthesized code. But there are a number of workarounds above, and the behavior cannot be changed due to the detection of directives; they are not peer-dependent.

Marking as closed since this is not feasible with the current directive parsing system.

[mirko772]

neomelodico Mirko privitera