Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Support multiple versions of YARD in a nice way.

  • Loading branch information...
commit 915097c0efe83f24c3ebc613fffa43e69cac1519 1 parent d69a7b6
@trans trans authored
View
47 lib/yard-tomdoc.rb
@@ -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
13 lib/yard-tomdoc/yard07.rb
@@ -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
32 lib/yard-tomdoc/yard08.rb
@@ -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 added a note

FYI this is public as of 0.8.1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ end
+
+end
View
22 lib/yard-tomdoc/yard09.rb
@@ -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 added a note

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

@lsegal
lsegal added a note

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 Owner
trans added a note

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 added a note

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

@lsegal
lsegal added a note

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ end
+
+ public :create_tag
+ end
+
+ # Set the parser as default when parsing
+ YARD::Docstring.default_parser = TomDocParser
+
+ # TODO: what about callback
+end
+
@lsegal

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

@lsegal

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?

@lsegal

FYI this is public as of 0.8.1

@trans

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

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

@lsegal

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.

Please sign in to comment.
Something went wrong with that request. Please try again.