class methods aren't cross referenced

[jfirebaugh]

# Test.test
class Test
  def self.test
  end
end

# Shortcut for Test.test
def Test
  Test.test
end

Neither instance of Test.test is linked in the output. Rdoc does so.

In addition, the summary for #Test reads "Shortcut for Test." rather than "Shortcut for Test.test"

[lsegal]

Hi,

YARD does not autolink class names. Everything is plain English unless otherwised marked up. You should use the {OBJECT} syntax to link a class method as code. The reason it stops at Test. is because the summary reads until the end of the first sentence (ending with a period)-- because this is all plaintext, the first sentence ends at "Test."-- You'd want {Test.test} if you need the method to be linked.

[jfirebaugh]

Thanks for the explanation.

This difference seems like it could be a barrier to adoption for projects considering switching from rdoc to yard, however. Is there a possibility for a switch to enable the rdoc cross-referencing behavior?

[jfirebaugh]

Hmm, when I try your suggestion, the summary ends up reading "Shortcut for {Test." It is linked correctly in the details.

[lsegal]

I don't think this would be a barrier to adoption. That would be like saying Textile's formatting could be a barrier to adoption to anyone using Markdown-- they're simply different markups. Frankly, I'd see the use of @param, @return and other tags a much bigger "barrier to entry" than having to add {} to the first instance of the class and method names in your docstrings.

That said, your report about {foo.bar} is right-- the CodeObjects::Base#summary method needs to be beefed up to handle more complex sentence content.

Another thing I should point out is if you're looking to document an inter-namespace "shortcut" (or any other reference), you should really consider using a @see tag:

# @see Test.test
def Test; end

[jfirebaugh]

Hi Loren,

Let me explain why I think it might be a barrier. I came across yard after browsing through rdoc-generated documentation for a lot of different projects and thinking "there must be something better." And yard looks great -- semantic markup, support for DSLs, extensible tags, and key for existing projects which are already invested in rdoc: compatible syntax. "By default, YARD is compatible with the same RDoc syntax most Ruby developers are already familiar with." This means that we can switch from rdoc to yard without immediately having to rewrite all the existing markup, and then incrementally begin using yardoc-specific tags to improve the existing documentation. In this scenario, each incompatibility with rdoc is a barrier to switching. If I have a lot of documentation which is (mostly) correctly cross-referenced by rdoc, and switching to yard would result in those cross-references disappearing until I go back and explicitly mark them all up, that becomes a reason for me not to switch. Not insurmountable by any means, but it will be the point at which someone considering yardoc is likely to go from thinking "yard looks great, and I think I'll be able to start using it in my projects without a lot of hassle" to "oh, it's going to take some work just to get back to the quality I had with rdoc." And that psychology will prevent people from switching, even if it turns out not to be that much work (for example, if it could largely be automated).

Thanks for the pointer too @see, I will check it out. And thanks for pushing the state of Ruby documentation tools forward.

John