Allow params that are common to all examples to be defined once on the class

[John Yeates]

Is your feature request related to a problem? Please describe

When writing a preview with multiple examples, it would be useful to be able to define common @param entries on the class rather than repeating them for each individual method — particularly for complicated select params.

Describe the solution you'd like

Instead of this

class TestComponentPreview < Lookbook::Preview
  # @param name text
  def default(name: 'Alice')
    render TestComponent.new(name: name)
  end

  # @param name text
  # @param icon text
  def with_icon(name: 'Alice', icon: '')
    render TestComponent.new(name: name, icon: icon)
  end

we could use this

# @param name text
class TestComponentPreview < Lookbook::Preview
  def default(name: 'Alice')
    render TestComponent.new(name: name)
  end

  # @param icon text
  def with_icon(name: 'Alice', icon: '')
    render TestComponent.new(name: name, icon: icon)
  end

and the name param would apply to default and with_icon.

Describe alternatives you've considered

I swear I saw something in the docs saying this was possible, but it doesn't work and I can't find it in the docs now. Which means I was probably looking at the view_component-storybook docs at the time 🤦

Additional context

Add any other context or screenshots about the feature request here.

[Mark Perkins]

@unikitty37 whilst I do like the idea of defining common params at the class level, there is indeed a (different) way of achieving this using YARD's 'reference tag' format: https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#reference-tags

Basically something like this:

  # @param icon text
  def default(name: 'Alice')
    render TestComponent.new(name: name)
  end

 # @param (see #default)
  def with_icon(name: 'Alice', icon: '')
    render TestComponent.new(name: name, icon: icon)
  end

The # @param (see #default) line will copy all params from the referenced method. Or you can just do this:

 # (see #default)
  def with_icon(name: 'Alice', icon: '')
    ...
  end

Which will copy over all annotation data from the reference method. More succinct if you are only defining params but if you are also adding notes etc it may not be what you want.

I don't think I've ever documented this but I certainly should do. I'll try and add something when I get chance :-)

[John Yeates]

Thanks — I didn't know about that!

I guess for the cases where there are some common params but no example that takes only the common params, you could use something like this:

# @hidden
# @param param1 text
# @param param2 number
def common_params(param1:, param2:) ; end

and then use @param (see #common_params) in the examples that are visible.

[Mark Perkins]

Yeah that should work! - I hadn't considered using a hidden scenario like that but it should work fine for that use case.

I do like your suggestion of setting common params at the class level though, some other tags work like that already so it would fit the existing patterns well. I'll add it to the list.

I'll go ahead and close this issue now but I'll try and get something into the docs about this as it's a useful feature for people :-)