README in lazydoc-0.2.0 vs README in lazydoc-0.3.0
- old
+ new
@@ -4,121 +4,98 @@
available in code through lazy attributes. Lazydoc is used by the
Tap[http://tap.rubyforge.org] framework.
== Description
-Lazydoc can find two types of documentation: constant attributes and
-code comments. To illustrate, consider the following:
+Lazydoc allows you to define lazy attributes that act as markers for
+documentation in a source file. When you call the lazy attribute,
+Lazydoc pulls out the documentation:
# Sample::key <value>
# This is the comment content. A content
# string can span multiple lines...
- #
- # code.is_allowed
- # much.as_in RDoc
- #
- # and stops at the next non-comment
- # line, the next constant attribute,
- # or an end key
class Sample
extend Lazydoc::Attributes
- self.source_file = __FILE__
-
lazy_attr :key
-
- # comment content for a code comment
- # may similarly span multiple lines
- def method_one
- end
end
-
-When a lazy attribute is called, Lazydoc scans <tt>source_file</tt> for
-the corresponding constant attribute and makes it available as a
-Lazydoc::Comment.
-
+
comment = Sample::key
- comment.value
- # => "<value>"
+ comment.value # => "<value>"
+ comment.comment # => "This is the comment content. A content string can span multiple lines..."
- comment.content
- # => [
- # ["This is the comment content. A content", "string can span multiple lines..."],
- # [""],
- # [" code.is_allowed"],
- # [" much.as_in RDoc"],
- # [""],
- # ["and stops at the next non-comment", "line, the next constant attribute,", "or an end key"]]
+Comments support wrapping, allowing for easy presentation:
- "\n#{'.' * 30}\n" + comment.wrap(30) + "\n#{'.' * 30}\n"
+ thirtydots = "\n#{'.' * 30}\n"
+
+ "#{thirtydots}#{comment.wrap(30)}#{thirtydots}"
# => %q{
# ..............................
# This is the comment content.
# A content string can span
# multiple lines...
- #
- # code.is_allowed
- # much.as_in RDoc
- #
- # and stops at the next
- # non-comment line, the next
- # constant attribute, or an end
- # key
# ..............................
# }
-In addition, individual lines of code may be registered and resolved by Lazydoc:
+In addition, Lazydoc provides helpers to register individual lines of code,
+particularly method definitions:
- doc = Sample.lazydoc.reset
- comment = doc.register(/method_one/)
-
- doc.resolve
- comment.subject # => " def method_one"
- comment.content # => [["comment content for a code comment", "may similarly span multiple lines"]]
-
-A variety of helper methods exist to register methods, in particular:
-
class Helpers
extend Lazydoc::Attributes
- register_method___
- # method_one was registered by the
- # helper
+ lazy_register(:method_one)
+
+ # method_one is registered whenever it
+ # gets defined
def method_one(a, b='str', &c)
end
- # method_two illustrates registration
- # of the line that *calls* method_two
+ # register_caller will register the line
+ # that *calls* method_two
def method_two
Lazydoc.register_caller
end
end
- # *THIS* is the line that gets registered
- # by method_two
- Helpers.new.method_two
+ # *THIS* is the line that gets
+ # registered by method_two
+ Helpers.const_attrs[:method_two] = Helpers.new.method_two
doc = Helpers.lazydoc
doc.resolve
- m1 = doc.comments[0]
- m1.method_name # => "method_one"
- m1.arguments # => ["a", "b='str'", "&c"]
- m1.to_s # => "method_one was registered by the helper"
+ one = Helpers.const_attrs[:method_one]
+ one.method_name # => "method_one"
+ one.arguments # => ["a", "b='str'", "&c"]
+ one.to_s # => "method_one is registered whenever it gets defined"
- comment = doc.comments[1]
- comment.subject # => "Helpers.new.method_two"
- comment.to_s # => "*THIS* is the line that gets registered by method_two"
+ two = Helpers.const_attrs[:method_two]
+ two.subject # => "Helpers.const_attrs[:method_two] = Helpers.new.method_two"
+ two.to_s # => "*THIS* is the line that gets registered by method_two"
+Lazy accessors may be defined to map the registered lines as well:
+
+ class Helpers
+ lazy_attr(:one, :method_one)
+ lazy_attr(:two, :method_two)
+ end
+
+ Helpers.one.method_name # => "method_one"
+ Helpers.two.subject # => "Helpers.const_attrs[:method_two] = Helpers.new.method_two"
+
Check out these links for development, and bug tracking.
* Website[http://tap.rubyforge.org/lazydoc]
* Github[http://github.com/bahuvrihi/lazydoc/tree/master]
* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/19948-lazydoc/tickets?q=all]
* {Google Group}[http://groups.google.com/group/ruby-on-tap]
== Usage
+Lazydoc can find two types of documentation, constant attributes and code
+comments. The distinction is primarily how they are found and parsed; both
+are represented by Comment objects.
+
=== Constant Attributes
Constant attributes are like constants in Ruby, but with an extra 'key'
that must consist of only lowercase letters and/or underscores. For
example, these are constant attributes:
@@ -132,12 +109,12 @@
# Const::Name::Key
# Const::Name::key2
# Const::Name::k@y
Lazydoc parses a Lazydoc::Comment for each constant attribute by using the
-remainder of the line as a value (ie subject) and scanning down for content.
-Scanning continues until a non-comment line, an end key, or a new attribute
+remainder of the line as a value (ie subject) and parsing down for content.
+Parsing continues until a non-comment line, an end key, or a new attribute
is reached; the comment is then stored by constant name and key.
str = %Q{
# Const::Name::key value for key
# comment for key
@@ -153,11 +130,11 @@
}
doc = Lazydoc::Document.new
doc.resolve(str)
- doc.to_hash {|comment| [comment.value, comment.to_s] }
+ doc.summarize {|c| [c.value, c.comment] }
# => {
# 'Const::Name' => {
# 'key' => ['value for key', 'comment for key parsed until a non-comment line'],
# 'another' => ['value for another', 'comment for another parsed to an end key']}
# }
@@ -174,11 +151,11 @@
# Const::Name::parsed value
}
doc = Lazydoc::Document.new
doc.resolve(str)
- doc.to_hash {|comment| comment.value } # => {'Const::Name' => {'parsed' => 'value'}}
+ doc.summarize {|comment| comment.value } # => {'Const::Name' => {'parsed' => 'value'}}
To hide attributes from RDoc, make use of the RDoc <tt>:startdoc:</tt>
document modifier like this (note that spaces are added to prevent RDoc
from hiding the example):
@@ -192,14 +169,13 @@
# Const::Name::two-
#++
#
# * This line is also visible in RDoc.
-As a side note, <tt>Const::Name::key</tt> is not a reference to the 'key'
-constant (as that would be invalid). In *very* idiomatic ruby
-<tt>Const::Name::key</tt> is equivalent to the method call
-<tt>Const::Name.key</tt>.
+As a side note, 'Const::Name::key' is not a reference to the 'key'
+constant (that would be invalid). In *very* idiomatic ruby
+'Const::Name::key' is equivalent to the method call 'Const::Name.key'.
=== Code Comments
Code comments are lines registered for parsing if and when a Lazydoc gets
resolved. Unlike constant attributes, the registered line is the comment
@@ -222,19 +198,19 @@
doc = Lazydoc::Document.new
doc.register(3)
doc.register(9)
doc.resolve(str)
- doc.comments.collect {|comment| [comment.subject, comment.to_s] }
+ doc.comments.collect {|c| [c.subject, c.comment] }
# => [
# ['def method', 'comment lines for the method'],
# ['def another_method', 'as in RDoc, the comment can be separated from the method']]
Comments may be registered to specific line numbers, or with a Proc or
Regexp that will determine the line number during resolution. In the case
of a Regexp, the first matching line is used; Procs receive an array of
lines and should return the line number that should be used. See
-Lazydoc::Comment#resolve for more details.
+{Comment#parse_up}[link://classes/Lazydoc/Comment.html] for more details.
== Installation
Lazydoc is available as a gem on RubyForge[http://rubyforge.org/projects/tap]. Use: