(PDOC-161) Add summary tag for short descriptions
#138
Conversation
|
|
||
| # Warn if a summary longer than 140 characters was provided | ||
| if object.has_tag?(:summary) && object.tag(:summary).text.length > 140 | ||
| log.warn "The length of the summary for function '#{object.name}' exceeds the recommended limit of 140 characters." |
There was a problem hiding this comment.
Should we distinguish between Puppet functions and Ruby functions in the warning?
|
@scotje I toyed with the idea of a new class on top of the Ruby and Puppet handlers to deal with that error message but I thought it ended up being more gross. I figured I'd just follow the convention that already exists for adding a public api tag in each of the handlers. I could look into simplifying it again if you want. As for the HTML, I'm not sure that there's a better way to do it. |
|
Is there somewhere we could put like a class method just so we have the logic and message all in one place, even if we still have to invoke it from each handler? (With an argument for the context it was invoked in so you can construct a specific message still.) |
|
@scotje sure, that seems reasonable. I'll look into it. |
|
I built the gem from @whopper 's branch and it worked just as expected. +1 to merge. |
whopper
force-pushed
the
PDOC-161/master/summary
branch
from
de557d6 to
23ebe11
Compare
This tag is primarily meant to be applied to Puppet classes, but it is also supported by every other construct that can be documented with strings.
whopper
force-pushed
the
PDOC-161/master/summary
branch
from
23ebe11 to
8178c0b
Compare
| module PuppetStrings::Yard::Handlers::Helpers | ||
| # Logs a warning if a summary tag has more than 140 characters | ||
| def self.validate_summary_tag(object) | ||
| if object.has_tag?(:summary) && object.tag(:summary).text.length > 140 |
There was a problem hiding this comment.
@scotje I stuck this in this Helper module for the Handlers. Does that seem reasonable?
whopper
force-pushed
the
PDOC-161/master/summary
branch
from
b831384 to
a3f00d0
Compare
This tag is primarily meant to be applied to Puppet classes,
but it is also supported by every other construct that can be
documented with strings.