Make rule descriptions easier to visually parse

[backus]

Yardstick output can be fairly difficult to parse when there are a lot of changes which could be made:

I think some formatting changes could mostly alleviate this. When it comes to rule descriptions I think we should make the following changes:

• [x] Include their YARD tag if possible (only one rule doesn't follow this right now)

  For example, prefer:

  lib/yardstick.rb:35: Yardstick.measure: The public/semipublic method should include an @example

  instead of

  lib/yardstick.rb:35: Yardstick.measure: The public/semipublic method should have an example specified

• [x] Consistent positioning in description for YARD tag in question. I would prefer at the beginning of each line.
• [x] API tags and recommended values should be bolded and underlined respectively. I also think colors would make the instructions easier to parse when there are a lot of them. For example:

[dkubb]

I agree with all of these.

[backus]

@dkubb for #34 so far I have the following descriptions:

>> puts Yardstick::Document.registered_rules.map(&:description)
@api should be specified
@api should be public, semipublic, or private
@api should be semipublic or private for protected methods
@api should be private for private methods
@example should be specified for public and semipublic methods
method summary should be specified
method summary should be less than or equal to 79 characters in length
method summary should not end in a period
method summary should be a single line
@return should be specified

[dkubb]

@backus should the rule output be ordered according to where the @ tag typically appears within the output? For example, the method summary stuff should be first, with @example second, @api last, and @return just before @api (with @yield and related in between`).

[backus]

That sounds good to me. I'll open a separate issue for this since the current PR is just about changing the look of the rule output not the ordering.