5

I have the following method that I would like to document using YARDoc.

# Here is my method
# @arg woop [Woop] *dangerous* this parameter is output to the screen
def shoop(woop)
  puts woop
end

This generates HTML where dangerous is in bold. Because I have to parse this output, I would like to have a custom HTML tag. In other words, I would like to make it so that when the following code comment is parsed by YARDoc, the word dangerous is surrounded by <div class="custom"></div> tags, instead of <b><\b> tags, make it much easier to parse with Nokogiri. Not to say that it is currently impossible to parse with Nokogiri, it's just a bit more awkward and vulnerable to changes in the YARD code.

# Here is my method
# @arg woop [Woop] **dangerous** this parameter is output to the screen
def shoop(woop)
  puts woop
end

Is there any functionality in YARD that allows me to accomplish this? I looked at creating custom templates, but that seems to be more in regards to parsing code. I then inspected creating a custom markdown template, but I didn't see how this could or should be accomplished. I'm starting to get the impression that I'm barking up the wrong tree and would appreciate a Google keyword thrown my way.

Why I'm trying to parse the HTML in the first place:
As I've described in previous questions, I'm trying to define an interface without having to duplicate code. In this example, I want a server to "call" a method that is dangerous differently than a method that is not dangerous.

Seanny123
  • 8,776
  • 13
  • 68
  • 124
  • Can you explain a bit more why you will need to parse the output? Perhaps there is some way of creating a custom output format that has the data you need, so you can avoid parsing the HTML. – Shepmaster Nov 04 '13 at 00:43
  • I've tried, but I'm afraid I don't know how to give much more detail without this question turning into a code review. – Seanny123 Nov 04 '13 at 04:29

1 Answers1

5

Markdown allows you to include inline html. So maybe try:

# Here is my method
# @arg woop [Woop] <div class="custom">dangerous</div> this ....
def shoop...
...

If this works, you could then override the default css in the doc/css/common.css file.

pandita
  • 4,739
  • 6
  • 29
  • 51
  • I didn't know about the css file, so thanks for that, but I would still rather not have inline HTML as this makes my documentation harder to read. – Seanny123 Nov 01 '13 at 09:28
  • The other way to do it then is maybe to redefine the `.bold` or `.strong` property in the css file. This way you could use the normal markdown but `*dangerous*` or `**dangerous**` would be formatted the way you wish? – pandita Nov 01 '13 at 09:37
  • 1
    It's not really the format that concerns me as much as the tags themselves, since I will be parsing this output with Nokogiri for other purposes. I've clarified this in my question now. – Seanny123 Nov 01 '13 at 10:00
  • 1
    Ah ok. Have a look at [this SO answer](http://stackoverflow.com/a/11467718/2488942) which describes how to handle custom tags from a html point of view. I know you said that you don't like inline html, but this might be a way to get there. You might be able to do something like `dangerous` and define some css for it. Definitely let me know if this works... – pandita Nov 01 '13 at 10:10
  • I see now that the custom tag idea was a bad choice. I've now edited my question to just mention custom class tags withing a div, since it provides the same functionality I'm looking for without the Javascript work-around. – Seanny123 Nov 01 '13 at 10:14