Jira (PDOC-156) Support @api tag for classes (in addition to functions)

William Hopper (JIRA) Wed, 11 Jan 2017 12:51:12 -0800

Title: Message Title

PDOC-156

I also just discovered that our handling of @api (in HTML) is buggy for functions. It only works for functions with multiple dispatches, and thus overload tags, i.e, this kind of works:

# Subtracts two things.

Puppet::Functions.create_function(:subtract) do

  # @api private

  dispatch :subtract_ints do

...

end

  dispatch :subtract_arrays do

...

end

  def subtract_ints(x, y)

    x - y

end

  def subtract_arrays(x, y)

    x - y

end

end

... but this doesn't:

# Subtracts two things.

Puppet::Functions.create_function(:subtract) do

  # @api private

  dispatch :subtract_ints do

...

end

  def subtract_ints(x, y)

    x - y

end

end

I believe this is because in the former, the docstring is wrapped in an overload tag which has its own template at lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb. This results in the overload having the bright warning in the HTML output, but only the overload which includes the tag. I think the presence of @api private for any overload should signify that they are all private, and the warning should be displayed above with the function overview.

Note that the JSON output always includes the tag, so the scope of this change is limited to HTML output.

Add Comment

This message was sent by Atlassian JIRA

--
You received this message because you are subscribed to the Google Groups "Puppet Bugs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/puppet-bugs.
For more options, visit https://groups.google.com/d/optout.

Jira (PDOC-156) Support @api tag for classes (in addition to functions)

Reply via email to