Moving all log message formatting to one class/module

17 views
Skip to first unread message

greg16....@gmail.com

unread,
Jul 3, 2016, 12:03:00 PM7/3/16
to YARD
Loren,

I've been working on using YARD / yard-t2 to generate docs from Ruby source (Core & Std-Lib).  At times, it would be helpful to reformat some of the log messages built into YARD.

For instance, most of the code in YARD::Templates::Helpers::HtmlHelper#resolve_links deals with (obviously) resolving the link, but it also may generates a log warning message.

Rather than redefine the whole method, it would be helpful to have #resolve_links pass all the message parameters to another class/module whose sole purpose is to format log message strings.

Hence, one could have a plugin / extension that reformatted the messages but left the YARD code as is.

Interested?  Thoughts?  I'd be happy to work on it.

Have a good Fourth,

Greg

Loren Segal

unread,
Jul 3, 2016, 1:57:40 PM7/3/16
to yar...@googlegroups.com

Hi Greg,

What are you looking to reformat exactly? Having a better understanding of the use case would be helpful.

Loren

--

---
You received this message because you are subscribed to the Google Groups "YARD" group.
To unsubscribe from this group and stop receiving emails from it, send an email to yardoc+un...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

greg16....@gmail.com

unread,
Jul 3, 2016, 2:27:15 PM7/3/16
to YARD
Only the log messages. To do so requires overriding methods that contain logic that doesn't need to be changed.

At present, if someone changes the format of the 'resolve_link' log message (by overriding resolve_link), then in the GitHub master the logic in the method was changed, someone with the ovverride wouldn't see the changes.

By moving the formatting to another class, most of those problems wouldn't occur (assuming the parameters of the call to its methods didn't change) .

Greg

Loren Segal

unread,
Jul 3, 2016, 3:36:48 PM7/3/16
to yar...@googlegroups.com

I'm still not sure I understand the purpose of changing the log messages. Can you provide a concrete use case and/or code that illustrates the issue?

Loren

--

greg16....@gmail.com

unread,
Jul 4, 2016, 12:39:49 AM7/4/16
to YARD
So I'm working with the Ruby source, and there's a lot of links that aren't properly doc'd in the comments.  I'm writing some code in t2 to try to parse them out, but some are across libraries (ie, from Core to a Lib or Ext), etc.

So then, I change the log level to see if YARD spits out any msgs if there's a link error (and it does, thank you).  So then, I've got several screens worth of warning, listed two lines each, etc.  I thought I'd reformat the msgs to be on a single line and more column based.

But, as I mentioned the resolve_links code has a bunch of logic in it *along with* the message formatting.  hence, splitting those two functions would be helpful in terms of 'separation of logic'...

As an example, in resolve_links, if str, file, line, and maybe some or all of [closed, tag, escape, name, title, match] were passed as parameters to another class for log formatting, someone trying to extend YARD wouldn't need to get into the real logic in the method.

I've seen several areas in YARD where you obviously gave thought to (and did a good job of) dividing logic up such that extending it wouldn't entail ripping it apart.   Removing the log formatting from the app logic is just another addition to that.
Reply all
Reply to author
Forward
0 new messages