Permalink
Browse files

Support multiple versions of YARD in a nice way.

  • Loading branch information...
1 parent d69a7b6 commit 915097c0efe83f24c3ebc613fffa43e69cac1519 @trans trans committed May 3, 2012
Showing with 72 additions and 42 deletions.
  1. +5 −42 lib/yard-tomdoc.rb
  2. +13 −0 lib/yard-tomdoc/yard07.rb
  3. +32 −0 lib/yard-tomdoc/yard08.rb
  4. +22 −0 lib/yard-tomdoc/yard09.rb
View
@@ -67,49 +67,12 @@ def self.yard_parse(yard, comment)
end
end
- if VERSION >= '0.8'
-
- class DocstringParser
- def parse(content, object = nil, handler = nil)
- @object = object
- @handler = handler
- @raw_text = content
-
- if object
- text = parse_tomdoc(content)
- else
- text = parse_content(content)
- end
-
- # Remove trailing/leading whitespace / newlines
- @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
- call_directives_after_parse
- call_after_parse_callbacks
-
- self
- end
-
- #
- def parse_tomdoc(content)
- tomdoc = TomDoc.yard_parse(self, content)
- tomdoc.description.to_s
- end
-
- public :create_tag
- end
-
+ if VERSION > '0.8'
+ require 'yard-tomdoc/yard09'
+ elsif VERSION == '0.8'
+ require 'yard-tomdoc/yard08'
else
-
- class Docstring
- def parse_comments(comments)
- comment = [comments].flatten.join("\n")
- tomdoc = TomDoc.yard_parse(self, comment)
- tomdoc.description.to_s # return the modified comment
- end
-
- public :create_tag
- end
-
+ require 'yard-tomdoc/yard07'
end
end
View
@@ -0,0 +1,13 @@
+module YARD
+
+ class Docstring
+ def parse_comments(comments)
+ comment = [comments].flatten.join("\n")
+ tomdoc = TomDoc.yard_parse(self, comment)
+ tomdoc.description.to_s # return the modified comment
+ end
+
+ public :create_tag
+ end
+
+end
View
@@ -0,0 +1,32 @@
+module YARD
+
+ class DocstringParser
+ def parse(content, object = nil, handler = nil)
+ @object = object
+ @handler = handler
+ @raw_text = content
+
+ if object
+ text = parse_tomdoc(content)
+ else
+ text = parse_content(content)
+ end
+
+ # Remove trailing/leading whitespace / newlines
+ @text = text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+ call_directives_after_parse
+ call_after_parse_callbacks
+
+ self
+ end
+
+ #
+ def parse_tomdoc(content)
+ tomdoc = TomDoc.yard_parse(self, content)
+ tomdoc.description.to_s
+ end
+
+ public :create_tag
@lsegal

lsegal May 3, 2012

Contributor

FYI this is public as of 0.8.1

+ end
+
+end
View
@@ -0,0 +1,22 @@
+module YARD
+
+ class TomDocParser < DocstringParser
+
+ def parse_content(content)
+ # TODO: move TomDoc.yard_parse code to here when old version are no longer supported
+ tomdoc = TomDoc.yard_parse(self, content)
+ text = tomdoc.description.to_s
+
+ # Remove trailing/leading whitespace / newlines
+ text.gsub(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
@lsegal

lsegal May 3, 2012

Contributor

FYI, text.gub() without assignment means your substitution will get lost! You might want gsub!, or (my preference) text = text.gsub(...)

@lsegal

lsegal May 3, 2012

Contributor

Actually I just realized that #parse_content has no return tag, even though it returns a String. It doesn't seem right that it returns the text portion. The #parse_content method should be setting the text attribute (since it sets tags attributes too). I might be making this change, requiring parse_content to make the modification rather than returning a value (and the return would become void). What do you think?

@trans

trans May 3, 2012

Owner

Since the method is inherently designed to be an in place modifier via #create_tag, that certainly would make sense. Would there be a proper interface for it, e.g. #set_description, or do we just use @text =?

@lsegal

lsegal May 3, 2012

Contributor

text/#text= is a public attribute on the parser, so you would set that, not the ivar directly (though technically you could).

@lsegal

lsegal May 3, 2012

Contributor

By the way, you can do: self.text = the_text_to_return in the last line of your method, and it would work for 0.8.1 and continue to work after we change the API, because it would return the text (for the 0.8.1 API) and set the value (for possible future versions).

edit: I just noticed that #text has no setter. Damn, guess we will add that. You can monkey patch that in without issue.

edit2: or use text.replace(). Yay for mutable Ruby strings.

+ end
+
+ public :create_tag
+ end
+
+ # Set the parser as default when parsing
+ YARD::Docstring.default_parser = TomDocParser
+
+ # TODO: what about callback
+end
+

0 comments on commit 915097c

Please sign in to comment.